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

git.iko.soy/urbit.org

Merge pull request #352 from urbit/link-fixes

Link fixes

commit462e5c1578c39ab8192dc764b950f87e6b7e85cf authorrmariani <robert@tlon.io> dateTue 22 Jan 2019, 16:03 (8 years ago) parent994e07e 3d8f3c2

43 files changed+124−103

compare with master

unifiedsplit

getting-started.udon+13

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

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

350350next section.

351351

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.

352365

353366;=

354367 ;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

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

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

1919- [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.

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

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

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

2222

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

2424

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)!

2626

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

2828- [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 @@

55 ==

66;>

8−# Community Docs

8+# Community Docs

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

1111

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

1313

1414- `~master-morzod`

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

16−- `~hidduc-posmeg`

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

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

1816- `~palfun-foslup`

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

2018- `@knubie`

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

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

143143```

144144

145145You 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

147147for booting a planet. That scheme is:

148148

149149```

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

162162

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

164164applications 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)

166166walkthroughs, respectively.

167167

168168

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

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

127127

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

129129`+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).

131131

132132```

133133/+ time-to-id

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

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

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

283283operations. For details on marks, see the

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

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

285285

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

287287```

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

535535sight.

536536

537537We'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

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

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

541541and 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

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

577577shortened to `|generator <args>`.

578578

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`,

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

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

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

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

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

585583

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

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

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

787785

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

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

790788

791789> 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

2929

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

3131changes. 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):

3333

3434```

3535> +echo 42

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

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

4747

4848##### `sys/hoon.hoon`

4949

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

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

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

5252

5353##### `sys/zuse.hoon`

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

104104

105105## app/

106106

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

108108servers, 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

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

111111

112112---

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

167167## web/

168168

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

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

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

171171

172172---

173173

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

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

2727

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

2929to 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).

3131

3232## Quickstart

3333

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

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

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

4444

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

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

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

4747

4848##### Serving

4949

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

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

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

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

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

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

9999

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

101101 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.

497497

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

499499subject 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

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

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

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

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

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

504504

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

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

3737~your-urbit:dojo< 2

3838```

3939

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

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

4242called faces, are stored.

4343

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

5959```

6060

6161(`%` 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))

6363

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

6565

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

264264

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

266266

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

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

268268

269269```

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

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

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

323323*Example:*

324324

325325```

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)

327327```

328328

329329###### Produces:

330330

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)

332332

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

334334the 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.

337337*Example:*

338338

339339```

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

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

341341```

342342

343343###### Produces:

344344

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

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

346346

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

348348examples should have the same destination.

349349

350350#### 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

2323

2424## Lessons

2525

26−;list;

26+-

2727

2828## Other Resources

2929

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.

3133

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.

3334

3435> Last major revision of this section: December 2018

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

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

11:- :~ navhome/'/docs/'

22 navuptwo/'true'

33 next/'true'

4− sort/'24'

4+ sort/'14'

55 title/'Arms and Cores'

66 ==

77;>

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

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

11:- :~ navhome/'/docs/'

22 navuptwo/'true'

33 next/'true'

4− sort/'30'

4+ sort/'24'

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

66 ==

77;>

9−# Atoms, Auras, and Simple Cell Types

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

1010

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

1212

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

2222

2323## Atoms and Auras

2424

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.

2626

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

2828

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

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

11:- :~ navhome/'/docs/'

22 navuptwo/'true'

33 next/'true'

4− sort/'34'

4+ sort/'26'

55 title/'Cores Again'

66 ==

77;>

9−# Cores Again

9+# 2.6 Cores Again

1010

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

1212

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

153153

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

155155

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.

157157

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

159159

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

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

11:- :~ navhome/'/docs/'

22 navuptwo/'true'

33 next/'true'

4− sort/'33'

4+ sort/'27'

55 title/'Cores'

66 ==

77;>

9−# Cores

9+2.7 Cores

1010

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

1212

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

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

11:- :~ navhome/'/docs/'

22 navuptwo/'true'

33 next/'true'

4− sort/'37'

4+ sort/'30'

55 title/'Examples'

66 ==

77;>

9−# Examples

9+# 2.10 Examples

1010

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

1212

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

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

11:- :~ navhome/'/docs/'

22 navuptwo/'true'

33 next/'true'

4− sort/'25'

4+ sort/'15'

55 title/'Gates (Hoon Functions)'

66 ==

77;>

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

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

11:- :~ navhome/'/docs/'

22 navuptwo/'true'

33 next/'true'

4− sort/'21'

4+ sort/'11'

55 title/'Getting Started'

66 ==

77;>

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

1212

1313## Installing Urbit

1414

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.

1616

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

1818

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

2626

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

2828

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.

3030

3131## Booting a Comet

3232

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

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

11:- :~ navhome/'/docs/'

22 navuptwo/'true'

33 next/'true'

4− sort/'27'

4+ sort/'21'

55 title/'Hoon Programs'

66 ==

77;>

9−# Writing Hoon Programs

9+# 2.1 Writing Hoon Programs

1010

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

1212

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

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

11:- :~ navhome/'/docs/'

22 navuptwo/'true'

33 next/'true'

4− sort/'28'

4+ sort/'22'

55 title/'Hoon Syntax'

66 ==

77;>

9−# Hoon Syntax

9+# 2.2 Hoon Syntax

1010

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

1212

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

93930b1101.1001

9494```

9595

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

9797

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

9999

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

160160

161161Runes 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.

162162

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.

164164

165165#### Tall and Flat Forms

166166

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

264264

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

266266

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.

268268

269269```

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

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

30830835

309309```

310310

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

312312

313313### Expressions That Are Only Irregular

314314

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

349349[16 18]

350350```

351351

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

353353

354354## Hoon Style

355355

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

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

11:- :~ navhome/'/docs/'

22 navuptwo/'true'

33 next/'true'

4− sort/'35'

4+ sort/'28'

55 title/'Standard Library: Lists'

66 ==

77;>

9−# Standard Library: Lists

9+# 2.8 Standard Library: Lists

1010

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

1212

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

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

11:- :~ navhome/'/docs/'

22 navuptwo/'true'

33 next/'true'

4− sort/'26'

4+ sort/'16'

55 title/'Multi-gate Cores and Doors'

66 ==

77;>

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

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

11:- :~ navhome/'/docs/'

22 navuptwo/'true'

33 next/'true'

4− sort/'22'

4+ sort/'12'

55 title/'Nouns'

66 ==

77;>

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

290290

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

292292

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

294294

295295## Cells

296296

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

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

11:- :~ navhome/'/docs/'

22 navuptwo/'true'

33 next/'true'

4− sort/'29'

4+ sort/'23'

55 title/'Simple One-Gate Programs'

66 ==

77;>

9−# Simple One-Gate Programs

9+# 2.3 Simple One-Gate Programs

1010

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

1212

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

1414

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

2020

2121The `|=` 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`.

2222

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.

2424

2525You 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:

2626

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

630630

631631This 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 `==`.

632632

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.

634634

635635### Decrement

636636

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

732732

733733Let'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'.

734734

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`:

736736

737737```

738738|= end=@ :: 1

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

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

11:- :~ navhome/'/docs/'

22 navuptwo/'true'

33 next/'true'

4− sort/'32'

4+ sort/'25'

55 title/'Structures and Complex Types'

66 ==

77;>

9−# Structures and Complex Types

9+# 2.5 Structures and Complex Types

1010

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

1212

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

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

11:- :~ navhome/'/docs/'

22 navuptwo/'true'

33 next/'true'

4− sort/'23'

4+ sort/'13'

55 title/'The Subject and Its Legs'

66 ==

77;>

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

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

11:- :~ navhome/'/docs/'

22 navuptwo/'true'

33 next/'true'

4− sort/'36'

4+ sort/'29'

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

66 ==

77;>

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

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

1010

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

1212

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

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

11:- :~ navhome/'/docs/'

22 navuptwo/'true'

33 next/'true'

4− sort/'31'

4+ sort/'24'

55 title/'Type Checking and Type Inference'

66 ==

77;>

9−# Type Checking and Type Inference

9+# 2.4 Type Checking and Type Inference

1010

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

1212

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

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

11:- :~ navhome/'/docs/'

22 navuptwo/'true'

3− sort/'38'

3+ sort/'31'

44 title/'Type Polymorphism'

55 ==

66;>

8−# Polymorphism

8+# 3.1 Polymorphism

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

1111

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

502502

503503You 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.

504504

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

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

506506

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

508508may 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

4545enforce the specific rules of the Urbit identity registry.

4646

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

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

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

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

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

reference.udon+9

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

77# Reference

99Various 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

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

2121

2222This 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).

2424

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

2626the cheat sheet:

reference/glossary.udon+2−3

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

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

713713the software stack and Urbit the network.

714714

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

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

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

717716

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

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

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

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

881880

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

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

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

884883

885884

886885### Unit

reference/hoon-expressions/advanced.udon+5

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

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

120120*bivariant*.

121121

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+

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

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

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

reference/hoon-expressions/irregular.udon−2

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

99##### `~palfun-foslup`

1010

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

12−

1311##### Reading guide

1412

1513Headings 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 @@

1212FNV scrambler

1313

1414Hashes 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

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

1717

1818#### Accepts

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

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

8181

8282#### Discussion

8383

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

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

8585

8686---

8787### `++map`

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

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

5555

5656Aura-atom pair

5757

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

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

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

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

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

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

6161to parse atoms of specific auras.

6262

6363#### Source

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

9898

9999#### Discussion

100100

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

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

102102

103103

104104---

reference/troubleshooting.udon+6−6

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

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

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

2424somewhere 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),

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

2727

2828```

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

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

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

104104trivial 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

106106any hoon in your stack trace.

107107

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

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

132132

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

134134`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.

136136

137137## Runtime crashes

138138

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

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

147147

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

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

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

150150

151151```

152152~| foo

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

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

163163functional language, but it still happens.

164164

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

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

166166This pretty-prints its argument:

167167

168168```

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

171171```

172172

173173will 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

175175true:

176176

177177```