335e47a · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

tutorials/hoon/1.1–1.2: text, typographic, and formatting corrections (#823)

335e47afakezod6 years ago

tutorials/_index.md+3−3

compare with master

unifiedsplit

@@ -14,14 +14,14 @@ Arvo is a clean-slate system software stack defined as a deterministic computer.

15## [Hoon Tutorial](@/docs/tutorials/hoon/_index.md)

17−Hoon 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. The Hoon Tutorial is the best place to start if you want to learn Urbit.

17+Hoon 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. The Hoon Tutorial is the best place to start if you want to learn Urbit.

19## [Nock](@/docs/tutorials/nock/_index.md)

21−Nock 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.

21+Nock 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.

23## [Vere](@/docs/tutorials/vere/_index.md)

25The Nock runtime system, written in C.

27−Keep reading if you’re planning to work on the Urbit interpreter, you’re a language implementation geek, or you don’t really understand anything until you’ve seen the actual structs.

27+Keep reading if you're planning to work on the Urbit interpreter, you're a language implementation geek, or you don't really understand anything until you've seen the actual structs.

tutorials/creating-an-invite-pool.md+6−6

@@ -4,13 +4,13 @@ weight = 9

4template = "doc.html"

5+++

7−If you’re a star owner, you have the ability to create **invite pools**. These invite pools let you give your friends a piece of the network in the form of planets. This document will give you an explanation of how to create an invite pool and how to share it with your friends using our tool [Bridge](https://bridge.urbit.org).

7+If you're a star owner, you have the ability to create **invite pools**. These invite pools let you give your friends a piece of the network in the form of planets. This document will give you an explanation of how to create an invite pool and how to share it with your friends using our tool [Bridge](https://bridge.urbit.org).

9For more general tips on using your star, check out the [Star and Galaxy Operations page](https://urbit.org/using/operations/stars-and-galaxies/).

11## Anatomy of an Invite Pool

13−An invite pool is a set of planet invites that can be distributed via email; each invite is worth one planet when redeemed. An invite pool can be as big as you’d like, providing that you have enough planets left to spawn. All invite pools must be created by a star, but they must be given to a planet. If you’re interested in how this works technically, take a look at the [DelegatedSending.sol contract](https://github.com/urbit/azimuth/blob/master/contracts/DelegatedSending.sol).

13+An invite pool is a set of planet invites that can be distributed via email; each invite is worth one planet when redeemed. An invite pool can be as big as you'd like, providing that you have enough planets left to spawn. All invite pools must be created by a star, but they must be given to a planet. If you're interested in how this works technically, take a look at the [DelegatedSending.sol contract](https://github.com/urbit/azimuth/blob/master/contracts/DelegatedSending.sol).

15Keep in mind that all planets will have access to the invite pool until the invite pool is exhausted.

@@ -22,17 +22,17 @@ Giving your friends a piece of Urbit only takes a few minutes: send an invite po

231. Log into Bridge using your ownership address for your star.

25−2. Get the name (like `~poldec-tonteg`) of the planet to whom you’d like to give invites, it can be one you control or a friend’s.

25+2. Get the name (like `~poldec-tonteg`) of the planet to whom you'd like to give invites, it can be one you control or a friend's.

27−3. Click “Manage Invite Pools” to assign an invite pool to the planet. You may receive a notification that you need to assign your spawn proxy to the address of the Delegated Sending contract. This is so that the contract can send invites on your behalf when the recipient claims them.

27+3. Click "Manage Invite Pools" to assign an invite pool to the planet. You may receive a notification that you need to assign your spawn proxy to the address of the Delegated Sending contract. This is so that the contract can send invites on your behalf when the recipient claims them.

29![](https://media.urbit.org/docs/invite-pool/browser-point.png)

31−4. Enter the planet name and the number of invites you’d like to assign them.

31+4. Enter the planet name and the number of invites you'd like to assign them.

33![](https://media.urbit.org/docs/invite-pool/browser-create-pool.png)

35−5. If you control the planet that you gave the invite pool to, it should be accessible from the Bridge homepage. Click the Planet, then “Invite” to create invites for your friends.

35+5. If you control the planet that you gave the invite pool to, it should be accessible from the Bridge homepage. Click the Planet, then "Invite" to create invites for your friends.

37![](https://media.urbit.org/docs/invite-pool/browser-invite.png)

tutorials/guide-to-breaches.md+6−6

@@ -10,7 +10,7 @@ There are two kinds of breaches: **personal breaches** and **network breaches**.

11## Personal Breaches

13−Ships on the Ames network sometimes need to reset their continuity. A personal breach is when an individual ship announces to the network: “I forgot who I am, let’s start over from scratch.” That is, it clears its own event log and sends an announcement to the network, asking all ships that have communicated with it to reset its networking information in their state. This makes it as though the ship was just started for the first time again, since everyone on the network has forgotten about it.

13+Ships on the Ames network sometimes need to reset their continuity. A personal breach is when an individual ship announces to the network: "I forgot who I am, let's start over from scratch." That is, it clears its own event log and sends an announcement to the network, asking all ships that have communicated with it to reset its networking information in their state. This makes it as though the ship was just started for the first time again, since everyone on the network has forgotten about it.

15Personal breaches often fix connectivity issues, but should only be used as a last resort. Before performing a personal breach, look at alternative fixes in the [Ship Troubleshooting](../ship-troubleshooting) guide. Also reach out for help in `~/~dopzod/urbit-help`, or, failing that, in the `#ship-starting-support` channel in our [Discord server](https://discord.gg/n9xhMdz) to see if there is another option.

@@ -28,17 +28,17 @@ There are two types of personal breaches: changing private keys, and changing

28the Ethereum address that holds the Urbit ID.

30Performing a personal breach on your ship increments an integer value called

31−your ship’s _life_ by one, which refers to your ship’s [Azimuth](@/docs/tutorials/concepts/azimuth.md) _key

31+your ship's _life_ by one, which refers to your ship's [Azimuth](@/docs/tutorials/concepts/azimuth.md) _key

32revision number_. This value is utilized by

33Ames and Jael to ensure that you are

34communicating with a ship created using its most recent set of keys. Your

35−ship’s life is written at the end of the name of its keyfile, e.g.

35+ship's life is written at the end of the name of its keyfile, e.g.

36`sampel-palnet-4.key`. Changing the Etherum address that holds the Urbit ID,

37−called _reticketing_, also increments a number called the ship’s _rift_ by one.

37+called _reticketing_, also increments a number called the ship's _rift_ by one.

38−Rift refers to your ship’s Azimuth _continuity number_.

38+Rift refers to your ship's Azimuth _continuity number_.

40You can check your current life and rift number by running the

41−`+keys our` generator in Dojo. You can inspect another ship’s life and rift can be checked by

41+`+keys our` generator in Dojo. You can inspect another ship's life and rift can be checked by

42running `+keys ~sampel-palnet`.

tutorials/hoon-errors.md+21−21

@@ -10,19 +10,19 @@ on debugging and verbose mode, and how to use debugging printfs.

11## Syntax errors

13−When you get a syntax error, you’ll see a message like:

13+When you get a syntax error, you'll see a message like:

15```

16syntax error at [10 12]

17```

19This is a line and column number; more exactly, the line and

20−column of the first byte the parser couldn’t interpret as part of

20+column of the first byte the parser couldn't interpret as part of

21a correct Hoon file. These values are always correct.

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

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

25−somewhere above, you’ve confused Hoon’s tall form by using the

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

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

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

@@ -32,29 +32,29 @@ a function call whose sample is a cell) has three subhoons:

32baz

33```

35−But if you make a mistake and write …

35+But if you make a mistake and write ...

37```hoon

38%+ foo

39bar

40```

42−… the parser will eat the next reference below and try to treat it as a

42+... the parser will eat the next reference below and try to treat it as a

43part of the `%+`. This can cause a cascading error somewhere

44below, usually stopped by a `==` or `--`.

46−When this happens, don’t panic! Binary search actually works

46+When this happens, don't panic! Binary search actually works

47quite well. Any reference can be stubbed out as `!!`. Find the

48prefix of your file that compiles, then work forward until

49the actual error appears.

51## Semantic errors

53−Now your code parses but doesn’t compile.

53+Now your code parses but doesn't compile.

55### Turn on debugging or verbose mode

57−Your first step should be to put a `!:` (“zapcol”) rune at the

57+Your first step should be to put a `!:` ("zapcol") rune at the

58top of the file. This is like calling the C compiler with `-g`;

59it tells the Hoon compiler to generate tracing references.

@@ -69,7 +69,7 @@ stack trace. An extensive stack trace tutorial is [below](#stack-trace-tutorial)

70### Error trace

72−If you have `!:` on, you’ll see an error trace, like:

72+If you have `!:` on, you'll see an error trace, like:

74```

75/~zod/home/0/gen/hello:<[7 3].[11 21]>

@@ -86,7 +86,7 @@ failed to compile, then the cause of the error (`nest-fail`).

87Hoon does not believe in inundating you with possibly irrelevant

88debugging information. Your first resort is always to just look

89−at the code and try to figure out what’s wrong. This practice

89+at the code and try to figure out what's wrong. This practice

90strengthens your Hoon muscles.

92(Consider the opposite extreme; imagine if you had a magic bot

@@ -95,8 +95,8 @@ wasted on compiler errors. Con: you never learn Hoon.)

96## Common errors

98−Moral fiber is all very well and good, but sometimes you’re

98+Moral fiber is all very well and good, but sometimes you're

99−stumped. Couldn’t the compiler help a little? These messages do

99+stumped. Couldn't the compiler help a little? These messages do

100mean something. Here are the three most common:

101

102### `nest-fail`

@@ -104,7 +104,7 @@ mean something. Here are the three most common:

104This is a type mismatch (`nest` is the Hoon typechecker). It

105means you tried to pound a square peg into a round hole.

106

107−What was the peg and what was the hole? Hoon doesn’t tell you by

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

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

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

110can use the `~!` rune ([**sigzap**](@/docs/reference/hoon-expressions/rune/sig.md#sigzap)) to print the type of any hoon in your stack trace.

@@ -118,13 +118,13 @@ your code to be:

118(foo bar)

119```

120

121−You’ll get the same `nest-fail`, but this will show the type of

121+You'll get the same `nest-fail`, but this will show the type of

122`bar`, then the type of the sample of the `foo` gate.

123

124### `find.foo`

125

126−A `find.foo` error means limb `foo` wasn’t found in the subject.

126+A `find.foo` error means limb `foo` wasn't found in the subject.

127−In other words, “undeclared variable.”

127+In other words, "undeclared variable".

128

129The most common subspecies of `find` error is `find.$`, meaning

130the empty name `$` was not found. This often happens when you

@@ -135,15 +135,15 @@ function.

135### `mint-vain` and `mint-lost`

136

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

138−`mint-vain` means this hoon is never executed. `mint-lost` means there’s a case in a `?-` ([**wuthep**](@/docs/reference/hoon-expressions/rune/wut.md#wuthep)) that isn’t handled.

138+`mint-vain` means this hoon is never executed. `mint-lost` means there's a case in a `?-` ([**wuthep**](@/docs/reference/hoon-expressions/rune/wut.md#wuthep)) that isn't handled.

139

140## Runtime crashes

141

142−If your code crashes at runtime or overflows the stack, you’ll

142+If your code crashes at runtime or overflows the stack, you'll

143−see a stack trace that looks just like the trace above. Don’t

143+see a stack trace that looks just like the trace above. Don't

144confuse runtime crashes with compilation errors, though.

145

146−If your code goes into an infinite loop, kill it with `ctrl-c` (you’ll

146+If your code goes into an infinite loop, kill it with `ctrl-c` (you'll

147need to be developing on the local console; otherwise, the

148infinite loop will time out either too slowly or too fast). The

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

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

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

166functional language, but it still happens.

167

168−`~&` ([**sigpam**](@/docs/reference/hoon-expressions/rune/sig.md#sigpam)) is Hoon’s debugging printf.

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

169This pretty-prints its argument:

170

171```hoon

tutorials/hoon/_index.md+2−2

@@ -6,12 +6,12 @@ template = "sections/docs/hoon.html"

6aliases = ["/docs/byte/0/", "/docs/byte", "/docs/learn/hoon/hoon-tutorial/"]

7+++

9−This 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. Each lesson falls into one of two categories: **readings**, which are prose-heavy explanations of Hoon fundamentals, and **walkthroughs**, which are line-by-line explanations of example programs. Walkthroughs are found between readings, offering a practical implementation of the concepts taught in the reading before.

9+This 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. Each lesson falls into one of two categories: **readings**, which are prose-heavy explanations of Hoon fundamentals, and **walkthroughs**, which are line-by-line explanations of example programs. Walkthroughs are found between readings, offering a practical implementation of the concepts taught in the reading before.

11Before you start, we recommend reading [Why Hoon?](https://urbit.org/blog/why-hoon/), a blog post by a Tlon engineer that justifies the existence and use of this peculiar language. This explainer gives useful context to all types of learners, but those new to programming will need to use Google frequently for the jargon.

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

15−Hoon is a 'subject-oriented' programming language -- every expression of Hoon is evaluated relative to a **subject**. The subject is a piece of data that represents the environment, or the context, of an expression. After reading Chapter 1 you should understand what the subject is and how to refer to its various parts. In this chapter you'll also learn about **[cores](/docs/glossary/core/)**, which are an important data structure in Hoon. Once you get the hang of [cores](/docs/glossary/core/) you'll be able to write your own functions in Hoon.

15+Hoon is a "subject-oriented" programming language -- every expression of Hoon is evaluated relative to a **subject**. The subject is a piece of data that represents the environment, or the context, of an expression. After reading Chapter 1 you should understand what the subject is and how to refer to its various parts. In this chapter you'll also learn about **[cores](/docs/glossary/core/)**, which are an important data structure in Hoon. Once you get the hang of [cores](/docs/glossary/core/) you'll be able to write your own functions in Hoon.

17Chapter 2 covers the type system, and writing apps, and the workings of the Arvo kernel.

tutorials/hoon/conditionals.md+20−12

@@ -5,7 +5,7 @@ template = "doc.html"

5aliases = ["/docs/learn/hoon/hoon-tutorial/conditionals/"]

6+++

8−In this lesson, we will write a generator that takes an integer and checks if it is an even number between 1 and 100. This will help demonstrate how boolean (true or false) conditional expressions work in Hoon.

8+In this lesson, we will write a generator that takes an integer and checks if it is an even number between `1` and `100`. This will help demonstrate how boolean (`true` or `false`) conditional expressions work in Hoon.

10```hoon

11:- %say

@@ -24,54 +24,61 @@ On the very first line, with `:- %say` we are beginning to create a generator o

24|= [* [n=@ud ~] ~]

25```

27−The code above builds a gate. The gate's first argument is a cell provided by Dojo that contains some system information we're not going to use, so we use `*` to indicate "any [noun](/docs/glossary/noun/)." The next cell is our arguments provided to the generator upon invocation at the `dojo`. Here we only want one `@ud` with the face `n`.

27+The code above builds a gate. The gate's first argument is a cell provided by Dojo that contains some system information we're not going to use, so we use `*` to indicate "any [noun](/docs/glossary/noun/)". The next cell is our arguments provided to the generator upon invocation at the Dojo. Here we only want one `@ud` with the face `n`.

29```hoon

30:- %noun

31```

33−This code is the third line of the `%say` "boilerplate," and it produces a `cask` with the head of `%noun`. We could use any `mark` here, but `%noun` is the most generic type, able to fit any data.

33+This code is the third line of the `%say` "boilerplate", and it produces a `cask` with the head of `%noun`. We could use any `mark` here, but `%noun` is the most generic type, able to fit any data.

35```hoon

36^- ?

37```

38−This line casts the output as a `flag`, which is a type whose values are `%.y` and `%.n` representing "yes" and "no". These behave as boolean values.

39+This line casts the output as a `flag`, which is a type whose values are `%.y` and `%.n` representing "yes" and "no". These behave as boolean values (`true` or `false`).

40+

40−Let's look at the conditional.

41+Let's look at the conditional:

42```hoon

43```hoon

43?& (gte n 1)

44?& (gte n 1)

44```

45```

46−`?&` (pronounced "wut-pam") takes in a list of Hoon expressions, terminated by `==`, that evaluate to a `flag` and returns the logical "AND" of these `flag`s. Most runes take a fixed number of children, but the handful that do not (such as `?&`) end their list of children with a terminating rune. In our context, that means that if the product of each of the children of `?&` is `%.y`, then the product of the entire `?&` expression is `%.y` as well. Otherwise, the product of the conditional `?&` is `%.n`.

47+`?&` (pronounced "wut-pam") takes in a list of Hoon expressions, terminated by `==`, that evaluate to a `flag` and returns the logical "AND" of these flags. Most runes take a fixed number of children, but the handful that do not (such as `?&`) end their list of children with a terminating rune. In our context, that means that if the product of each of the children of `?&` is `%.y`, then the product of the entire `?&` expression is `%.y` as well. Otherwise, the product of the conditional `?&` is `%.n`.

48−The first child of `?&` is `(gte n 1)`. It is good practice to put the first boolean test of a conditional on the same line as the conditional as we have done here. This utilizes the standard library function `gte` which stands for "greater than or equal to". `(gte a b)` returns `%.y` if `a` is greater than or equal to `b`, and `%.n` otherwise.

49+The first child of `?&` is `(gte n 1)`. It is good practice to put the first boolean test of a conditional on the same line as the conditional, as we have done here. This utilizes the standard library function `gte` which stands for "greater than or equal to". `(gte a b)` returns `%.y` if `a` is greater than or equal to `b`, and `%.n` otherwise.

50Next we have:

51Next we have:

52+

51```hoon

53```hoon

52 (lte n 100)

54 (lte n 100)

53```

55```

56+

54`lte` is the standard library function for "less than or equal to". `(lte a b)` returns `%.y` if `a` is less than `b`, and `%.n` otherwise.

57`lte` is the standard library function for "less than or equal to". `(lte a b)` returns `%.y` if `a` is less than `b`, and `%.n` otherwise.

56−The last boolean test we have is

59+The last boolean test we have is:

60+

57```hoon

61```hoon

58 =(0 (mod n 2))

62 =(0 (mod n 2))

59```

63```

64+

60−This checks to see if `0` is equal to `(mod n 2)` - in other words, checking if `n` is even. It produces `%.y` if `n` is even and `%.n` if `n` is odd.

65+This checks to see if `0` is equal to `(mod n 2)` -- in other words, checking if `n` is even. It produces `%.y` if `n` is even and `%.n` if `n` is odd.

62It is good practice in Hoon to put "lighter" lines at the top and "heavier" lines at the bottom, which is why we have put `=(0 (mod n 2))` last in the list of conditionals.

67It is good practice in Hoon to put "lighter" lines at the top and "heavier" lines at the bottom, which is why we have put `=(0 (mod n 2))` last in the list of conditionals.

64−Finally we have a terminator.

69+Finally we have a terminator:

70+

65```hoon

71```hoon

66==

72==

67```

73```

74+

68This marks the end of the list of children of `?&`.

75This marks the end of the list of children of `?&`.

70### Other Runes

77### Other Runes

72We only utilized one "wut" rune in our walkthrough, but there are many others. Here are a few more examples:

79We only utilized one "wut" rune in our walkthrough, but there are many others. Here are a few more examples:

74−- `?:` (pronounced "wut-col") is the simplest "wut" rune. It takes three children, also called sub-expressions. The first child is a boolean test, so it looks for a `%.y` or a `%.n`. The second child is a yes-branch, which is what we arrive at if the aforementioned boolean test evaluates to `%.y`. The third child is a no-branch, which we arrive at if the boolean test evaluates to `%.n`. These branches can contain any sort of Hoon expression, including further conditional expressions. Instead of the `?&` expression in our `%say` generator above, we could have written

81+- `?:` (pronounced "wut-col") is the simplest "wut" rune. It takes three children, also called subexpressions. The first child is a boolean test, so it looks for a `%.y` or a `%.n`. The second child is a yes-branch, which is what we arrive at if the aforementioned boolean test evaluates to `%.y`. The third child is a no-branch, which we arrive at if the boolean test evaluates to `%.n`. These branches can contain any sort of Hoon expression, including further conditional expressions. Instead of the `?&` expression in our `%say` generator above, we could have written:

76```hoon

83```hoon

77?: ?& (gte n 1)

84?: ?& (gte n 1)

@@ -81,7 +88,8 @@ We only utilized one "wut" rune in our walkthrough, but there are many others. H

81 %.y

88 %.y

82%.n

89%.n

83```

90```

91+

84−Of course, doing so would be needlessly obfuscating - we mention this only to illustrate that these two Hoon expressions have the same product.

92+Of course, doing so would be needlessly obfuscating -- we mention this only to illustrate that these two Hoon expressions have the same product.

86- `?!` ("wut-zap") is the logical "NOT" operator, which inverts the truth value of its single child. Instead of `(lte n 100)` in our `%say` generator above, we could have written `?! (gth n 100)`. Again, this would be bad practice, we only present this as an example.

94- `?!` ("wut-zap") is the logical "NOT" operator, which inverts the truth value of its single child. Instead of `(lte n 100)` in our `%say` generator above, we could have written `?! (gth n 100)`. Again, this would be bad practice, we only present this as an example.

tutorials/hoon/fibonacci.md+6−6

@@ -5,7 +5,7 @@ template = "doc.html"

5aliases = ["/docs/learn/hoon/hoon-tutorial/fibonacci/"]

6+++

8−In this example, we will write a generator that produces a list of Fibonacci numbers up to `n`.

8+In this example, we will write a generator that produces a list of [Fibonacci numbers](https://en.wikipedia.org/wiki/Fibonacci_number) up to `n`.

10```hoon

11|= n=@ud

@@ -21,21 +21,21 @@ In this example, we will write a generator that produces a list of Fibonacci num

21==

22```

24−On the first line, we use `|=` to produce a [gate](/docs/glossary/gate/) which takes an `@ud` that's stored in the face `n`. This `n` sample that we give our [gate](/docs/glossary/gate/) determines how long our Fibonacci sequence is. When the list that our program builds has `n` members, the program ends.

24+On the first line, we use `|=` to produce a [gate](/docs/glossary/gate/) which takes an `@ud` that's stored in the face `n`. This `n` sample that we give our [gate](/docs/glossary/gate/) determines how long our Fibonacci sequence is. When the list that our program builds has `n` items, the program ends.

26```hoon

27%- flop

28```

30−In the line above, we use `flop` on the output of the rest of the program. `flop` is a standard library function to reverse a list.

30+In the line above, we use `flop` on the output of the rest of the program. `flop` is a [standard library](https://urbit.org/docs/reference/library/) function to reverse a list.

32−Why are we using this instead of just producing the list in the order we want it in the first place? Because with lists, adding an element to the end is a computationally expensive operation that gets more expensive the longer the list is, due to the fact that you need to traverse to the end of the tree. Adding an element to the front, however, is cheap. [In Big-O Notation](https://en.wikipedia.org/wiki/Big_O_notation), adding to the end of a list is O(n) and the front is O(1).

32+Why are we using this instead of just producing the list in the order we want it in the first place? Because with lists, adding an element to the end is a computationally expensive operation that gets more expensive the longer the list is, due to the fact that you need to traverse to the end of the tree. Adding an element to the front, however, is cheap. [In Big-O notation](https://en.wikipedia.org/wiki/Big_O_notation), adding to the end of a list is O(n) and the front is O(1).

34```hoon

35=+ [i=0 p=0 q=1 r=*(list @ud)]

36```

38−Here we declare several values that we are going to use during the execution of our program. The only one of these that is noteworthy is `r`: we're using `*` to bunt, or get the default value for, the mold `(list @ud)`.

38+Here we declare several values that we are going to use during the execution of our program. The only one that is noteworthy is `r`: we're using `*` to bunt, or get the default value for, the mold `(list @ud)`.

40```hoon

41|- ^+ r

@@ -47,7 +47,7 @@ With this code, we define `|-`, the _trap_ that acts as a recursion point and co

47?: =(i n) r

48```

50−In the code above, `?:` checks whether the first child, `=(i n)`, our terminating case, is true or false. If it is true, it branches to `r` and the program ends. If it is false, the program continues to the code below.

50+In the code above, `?:` checks whether the first child, `=(i n)` (our terminating case), is `true` or `false`. If it is `true`, it branches to `r` and the program ends. If it is `false`, the program continues to the code below.

52```hoon

53%= $

tutorials/hoon/gates.md+36−35

@@ -4,17 +4,18 @@ weight = 6

4template = "doc.html"

5aliases = ["/docs/learn/hoon/hoon-tutorial/gates/"]

6+++

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

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

9## What is a Function?

10## What is a Function?

11−The word 'function' is used in various ways, but let's start by talking about them in the [mathematical sense](https://en.wikipedia.org/wiki/Function_%28mathematics%29). Roughly put, a function takes one or more arguments (i.e., input values) and returns a value. The return value depends solely on the argument(s), and nothing else. For example, we can understand multiplication as a function: it takes two numbers and returns another number. It doesn't matter where you ask, when you ask, or what kind of hat you're wearing when you ask. If you pass the same two numbers (e.g., `3` and `4`), you get the same answer returned every time (`12`).

12+The word "function" is used in various ways, but let's start by talking about them in the [mathematical sense](https://en.wikipedia.org/wiki/Function_%28mathematics%29). Roughly put, a function takes one or more arguments (i.e., input values) and returns a value. The return value depends solely on the argument(s), and nothing else. For example, we can understand multiplication as a function: it takes two numbers and returns another number. It doesn't matter where you ask, when you ask, or what kind of hat you're wearing when you ask. If you pass the same two numbers (e.g., `3` and `4`), you get the same answer returned every time (`12`).

13−That output value depends solely upon input value(s) is an important property of functions. This property is called [referential transparency](https://en.wikipedia.org/wiki/Referential_transparency), and we make use of it throughout the Urbit software stack.

14+That output value depends solely upon input value(s) is an important property of functions. This property is called [referential transparency](https://en.wikipedia.org/wiki/Referential_transparency), and we make use of it throughout the Urbit software stack.

15−Functions are implemented in Hoon with a special kind of [core](/docs/glossary/core/) called a **gate**. In this lesson you'll learn what a [gate](/docs/glossary/gate/) is and how a gate represents a function. Along the way you'll build some example gates of your own.

16+Functions are implemented in Hoon with a special kind of [core](/docs/glossary/core/) called a **gate**. In this lesson you'll learn what a [gate](/docs/glossary/gate/) is and how a gate represents a function. Along the way you'll build some example gates of your own.

17−You've already used two functions from the Hoon standard library: `add` and `mul`. These are implemented with gates, and you call them from the dojo in the following way:

18+You've already used two functions from the Hoon standard library: `add` and `mul`. These are implemented with gates, and you call them from the Dojo in the following way:

19```

20```

20> (add 2 3)

21> (add 2 3)

@@ -28,7 +29,7 @@ You've already used two functions from the Hoon standard library: `add` and `mul

29A core is a cell: `[battery payload]`.

30A core is a cell: `[battery payload]`.

31−A gate is a core with two distinctive properties: (1) the battery of a gate contains exactly one [arm](/docs/glossary/arm/), which has the special name `$`. The `$` [arm](/docs/glossary/arm/) contains the instructions for the function in question. And (2), the payload of a gate consists of a cell of `[sample context]`. The sample is the part of the payload that stores the 'argument' (i.e., input value) of the function call. The context contains all other data that is needed for computing the `$` [arm](/docs/glossary/arm/) of the gate correctly.

32+A gate is a core with two distinctive properties: (1) the battery of a gate contains exactly one [arm](/docs/glossary/arm/), which has the special name `$`. The `$` [arm](/docs/glossary/arm/) contains the instructions for the function in question. And (2), the payload of a gate consists of a cell of `[sample context]`. The sample is the part of the payload that stores the "argument" (i.e., input value) of the function call. The context contains all other data that is needed for computing the `$` [arm](/docs/glossary/arm/) of the gate correctly.

33```

34```

34Gate: [$ [Sample Context]]

35Gate: [$ [Sample Context]]

@@ -44,11 +45,11 @@ As a tree, a gate looks like the following:

44 Sample Context

45 Sample Context

45```

46```

47−Like all arms, `$` is computed with its parent core as the subject. When `$` is computed, the resulting value is called the 'product' of the gate. No other data is used to calculate the product other than the data in the gate itself.

48+Like all arms, `$` is computed with its parent core as the subject. When `$` is computed, the resulting value is called the "product" of the gate. No other data is used to calculate the product other than the data in the gate itself.

49## Creating Your First Gate

50## Creating Your First Gate

51−Let's make a gate that takes any unsigned integer (i.e., an [atom](/docs/glossary/atom/)) as its sample and returns that value plus one as the product. To do this we'll use the `|=` rune. We'll bind this gate to the face `inc` for 'increment':

52+Let's make a gate that takes any unsigned integer (i.e., an [atom](/docs/glossary/atom/)) as its sample and returns that value plus one as the product. To do this we'll use the `|=` rune. We'll bind this gate to the face `inc` for "increment":

53```

54```

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

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

@@ -63,21 +64,21 @@ Let's make a gate that takes any unsigned integer (i.e., an [atom](/docs/glossar

63124

64124

64```

65```

66−The gate works as promised -- it takes any number `n` and returns `n + 1`. Let's take a closer look at what the `|=` is doing.

67+The gate works as promised -- it takes any number `n` and returns `n+1`. Let's take a closer look at what the `|=` is doing.

68### The `|=` Rune

69### The `|=` Rune

70−We typically use the `|=` rune to create a gate. In the expression above the `|=` is immediately followed by a set of parentheses containing two subexpressions: `a=@` and `(add 1 a)`. The first defines the gate's sample (input value type), and the second defines the gate's product (value).

71+We typically use the `|=` rune to create a gate. In the expression above the `|=` is immediately followed by a set of parentheses containing two subexpressions: `a=@` and `(add 1 a)`. The first defines the gate's sample (input value type), and the second defines the gate's product (value).

72−In the example gate above, `inc`, the sample is defined by `a=@`. This means that the sample is defined as an atom, `@`, meaning that the gate will take as input anything of that type. The sample is given the face `a`. With the face it's easier to refer to the sample in later code, if desired.

73+In the example gate above, `inc`, the sample is defined by `a=@`. This means that the sample is defined as an atom, `@`, meaning that the gate will take as input anything of that type. The sample is given the face `a`. With the face it's easier to refer to the sample in later code, if desired.

74−In `inc`, the product is defined by `(add 1 a)`. There's not much to it -- it returns the value of `a + 1`!

75+In `inc`, the product is defined by `(add 1 a)`. There's not much to it -- it returns the value of `a+1`!

76−The second subexpression after the `|=` rune is used to build the gate's `$` arm. That's where all the computations go.

77+The second subexpression after the `|=` rune is used to build the gate's `$` arm. That's where all the computations go.

78## Anatomy of a Gate

79## Anatomy of a Gate

80−A gate is a one-armed core with a sample: `[$ [Sample Context]]`. Let's go over these parts a little more carefully, using `inc` as our example.

81+A gate is a one-armed core with a sample: `[$ [Sample Context]]`. Let's go over these parts a little more carefully, using `inc` as our example.

82```

83```

83> inc

84> inc

@@ -93,27 +94,27 @@ A gate is a one-armed core with a sample: `[$ [Sample Context]]`. Let's go over

94The arm of a gate encodes the instructions for the Hoon function in question.

95The arm of a gate encodes the instructions for the Hoon function in question.

96−The pretty printer represents the `$` arm of `inc` as `1.jgn`. To see the actual [noun](/docs/glossary/noun/) of the `$` arm, enter `+2:inc` into the dojo:

97+The pretty printer represents the `$` arm of `inc` as `1.jgn`. To see the actual [noun](/docs/glossary/noun/) of the `$` arm, enter `+2:inc` into the Dojo:

98```

99```

99> +2:inc

100> +2:inc

100[8 [9 8 0 4.095] 9 2 [0 4] [[7 [0 3] 1 1] 0 14] 0 11]

101[8 [9 8 0 4.095] 9 2 [0 4] [[7 [0 3] 1 1] 0 14] 0 11]

101```

102```

102

103

103−This is un-computed Nock. You don't need to understand any of this.

104+This is un-computed Nock. You don't need to understand any of this.

104

105

105−It's worth pointing out that the arm name, `$`, can be used like any other name. We can compute `$` directly with `$:inc` in the dojo:

106+It's worth pointing out that the arm name, `$`, can be used like any other name. We can compute `$` directly with `$:inc` in the Dojo:

106

107

107```

108```

108> $:inc

109> $:inc

1091

1101

110```

111```

111

112

112−This result may seem a bit strange. We didn't call `inc` or in any other way pass it a number. Yet using `$` to evaluate `inc`'s arm seems to work -- sort of, anyway. Why is it giving us `1` as the return value? We can answer this question after we understand gate samples a little better.

113+This result may seem a bit strange. We didn't call `inc` or in any other way pass it a number. Yet using `$` to evaluate `inc`'s arm seems to work -- sort of, anyway. Why is it giving us `1` as the return value? We can answer this question after we understand gate samples a little better.

113

114

114### The Sample

115### The Sample

115

116

116−The sample of a gate is the address reserved for storing the argument(s) to the Hoon function. The sample is always at the head of the gate's tail, i.e., `+6`.

117+The sample of a gate is the address reserved for storing the argument(s) to the Hoon function. The sample is always at the head of the gate's tail, i.e., `+6`.

117

118

118Let's look at the gate for `inc` again, paying particular attention to its sample:

119Let's look at the gate for `inc` again, paying particular attention to its sample:

119

120

@@ -127,27 +128,27 @@ Let's look at the gate for `inc` again, paying particular attention to its sampl

127>

128>

128```

129```

129

130

130−We see `a/@`. This may not be totally clear, but it should make _some_ sense. This is the pretty-printer's way of indicating an atom with the face `a`. Let's take a closer look:

131+We see `a/@`. This may not be totally clear, but it should make _some_ sense. This is the pretty-printer's way of indicating an atom with the face `a`. Let's take a closer look:

131

132

132```

133```

133> +6:inc

134> +6:inc

134a=0

135a=0

135```

136```

136

137

137−We see now that the sample of `inc` is the value `0`, and has `a` as a face. This is a placeholder value for the function argument. If you evaluate the `$` arm of `inc` without passing it an argument the placeholder value is used for the computation, and the return value will thus be `0 + 1`:

138+We see now that the sample of `inc` is the value `0`, and has `a` as a face. This is a placeholder value for the function argument. If you evaluate the `$` arm of `inc` without passing it an argument the placeholder value is used for the computation, and the return value will thus be `0+1`:

138

139

139```

140```

140> $:inc

141> $:inc

1411

1421

142```

143```

143

144

144−The placeholder value is sometimes called a **bunt** value. The bunt value is determined by the input type; for atoms, `@`, the bunt value is `0`.

145+The placeholder value is sometimes called a **bunt** value. The bunt value is determined by the input type; for atoms, `@`, the bunt value is `0`.

145

146

146−The face value of `a` comes from the way we defined the gate above: `|=(a=@ (add 1 a))`. It was so we could use `a` to refer to the sample to generate the product with `(add 1 a)`.

147+The face value of `a` comes from the way we defined the gate above: `|=(a=@ (add 1 a))`. It was so we could use `a` to refer to the sample to generate the product with `(add 1 a)`.

147

148

148### The Context

149### The Context

149

150

150−The context of a gate contains other data that may be necessary for the `$` arm to evaluate correctly. The context always located at the tail of the tail of the gate, i.e., `+7` of the gate. There is no requirement that the context have any particular arrangement, though often it does.

151+The context of a gate contains other data that may be necessary for the `$` arm to evaluate correctly. The context is always located at the tail of the tail of the gate, i.e., `+7` of the gate. There is no requirement for the context to have any particular arrangement, though often it does.

151

152

152Let's look at the context of `inc`:

153Let's look at the context of `inc`:

153

154

@@ -164,28 +165,28 @@ Let's look at the context of `inc`:

164]

165]

165```

166```

166

167

167−This is exactly the default dojo subject, from before we put `inc` into the subject. The `|=` expression defines the context as whatever the subject is. This guarantees that the context has all the information it needs to have for the `$` arm to work correctly.

168+This is exactly the default Dojo subject, from before we put `inc` into the subject. The `|=` expression defines the context as whatever the subject is. This guarantees that the context has all the information it needs to have for the `$` arm to work correctly.

168

169

169### Exercise 1.4.1a

170### Exercise 1.4.1a

170

171

171−Write a gate that takes an atom, `a=@`, and which returns double the value of `a`. Bind this gate to `double` and test it in the dojo. A solution is given at the end of this lesson.

172+Write a gate that takes an atom, `a=@`, and which returns double the value of `a`. Bind this gate to `double` and test it in the Dojo. A solution is given at the end of this lesson.

172

173

173## Gates Define Functions of the Sample

174## Gates Define Functions of the Sample

174

175

175−The value of a function's output depends solely upon the input value. This is one of the features that make functions desirable in many programming contexts. It's worth going over how Hoon function calls implement this feature.

176+The value of a function's output depends solely upon the input value. This is one of the features that make functions desirable in many programming contexts. It's worth going over how Hoon function calls implement this feature.

176

177

177−In Hoon one can use `(gate arg)` syntax to make a function call. For example,

178+In Hoon, one can use `(gate arg)` syntax to make a function call. For example:

178

179

179```

180```

180> (inc 234)

181> (inc 234)

181235

182235

182```

183```

183

184

184−The name of the gate is `inc`. How is the `$` arm of `inc` evaluated? When a function call occurs, a copy of the `inc` gate is created, but with one modification; the sample is replaced with the function argument. Then the `$` arm is computed against this modified version of the `inc` gate.

185+The name of the gate is `inc`. How is the `$` arm of `inc` evaluated? When a function call occurs, a copy of the `inc` gate is created, but with one modification; the sample is replaced with the function argument. Then the `$` arm is computed against this modified version of the `inc` gate.

185

186

186−Remember that the default or 'bunt' value of the sample of `inc` is `0`. In the function call above, a copy of the `inc` gate is made but with a sample value of `234`. When `$` is computed against this modified core, the product is `235`.

187+Remember that the default or "bunt" value of the sample of `inc` is `0`. In the function call above, a copy of the `inc` gate is made but with a sample value of `234`. When `$` is computed against this modified core, the product is `235`.

187

188

188−Notice that neither the arm nor the context is modified before the arm is evaluated. That means that the only part of the gate that changes before the arm evaluation is the sample. Hence, we may understand each gate as defining a function whose argument is the sample. If you call a gate with the same sample, you'll get the same value returned to you every time.

189+Notice that neither the arm nor the context is modified before the arm is evaluated. That means that the only part of the gate that changes before the arm evaluation is the sample. Hence, we may understand each gate as defining a function whose argument is the sample. If you call a gate with the same sample, you'll get the same value returned to you every time.

189

190

190Let's unbind `inc` to keep the subject tidy:

191Let's unbind `inc` to keep the subject tidy:

191

192

@@ -198,7 +199,7 @@ Let's unbind `inc` to keep the subject tidy:

198

199

199### Modifying the Context of a Gate

200### Modifying the Context of a Gate

200

201

201−It _is_ possible to modify the context of a gate when you make a function call; or, to be more precise, it's possible to call a mutant copy of the gate in which the context is modified. To illustrate this let's use another example gate. Let's write a gate which uses a value from the context to generate the product. Bind `b` to the value `10`:

202+It _is_ possible to modify the context of a gate when you make a function call; or, to be more precise, it's possible to call a mutant copy of the gate in which the context is modified. To illustrate this let's use another example gate. Let's write a gate which uses a value from the context to generate the product. Bind `b` to the value `10`:

202

203

203```

204```

204> =b 10

205> =b 10

@@ -222,7 +223,7 @@ Now let's write a gate called `ten` that adds `b` to the input value:

22235

22335

223```

224```

224

225

225−We can unbind `b` from the dojo subject, and `ten` works just as well because it's using a copy of `b` stored its context:

226+We can unbind `b` from the Dojo subject, and `ten` works just as well because it's using a copy of `b` stored its context:

226

227

227```

228```

228> =b

229> =b

@@ -237,7 +238,7 @@ We can unbind `b` from the dojo subject, and `ten` works just as well because it

23710

23810

238```

239```

239

240

240−We can use `ten(b 25)` to produce a variant of `ten`. Calling this mutant version of `ten` causes a different value to be returned than we'd get with a normal `ten` call:

241+We can use `ten(b 25)` to produce a variant of `ten`. Calling this mutant version of `ten` causes a different value to be returned than we'd get with a normal `ten` call:

241

242

242```

243```

243> (ten(b 25) 10)

244> (ten(b 25) 10)

@@ -256,9 +257,9 @@ Before finishing the lesson let's unbind `ten`:

256> =ten

257> =ten

257```

258```

258

259

259−## Exercise 1.4.1a Solution

260+## Exercise 1.4.1a: Answer

260

261

261−Write a gate that takes an atom, `a=@`, and which returns double the value of `a`. Bind this gate to `double` and test it in the dojo.

262+Write a gate that takes an atom, `a=@`, and which returns double the value of `a`. Bind this gate to `double` and test it in the Dojo.

262

263

263```

264```

264> =double |=(a=@ (mul 2 a))

265> =double |=(a=@ (mul 2 a))

tutorials/hoon/hoon-syntax.md+54−54

@@ -7,22 +7,22 @@ aliases = ["/docs/learn/hoon/hoon-tutorial/hoon-syntax/"]

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

10−The [syntax](https://en.wikipedia.org/wiki/Syntax_%28programming_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.

10+The [syntax](https://en.wikipedia.org/wiki/Syntax_%28programming_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.

12−The [semantics](https://en.wikipedia.org/wiki/Semantics_%28computer_science%29 ) of a programming language concerns the meaning of the various parts of that language's code.

12+The [semantics](https://en.wikipedia.org/wiki/Semantics_%28computer_science%29 ) of a programming language concerns the meaning of the various parts of that language’s code.

14−In this lesson we will give a general overview of Hoon's syntax. By the end of it, you should be familiar with all the basic elements of Hoon code.

14+In this lesson we will give a general overview of Hoon’s syntax. By the end of it, you should be familiar with all the basic elements of Hoon code.

16## Hoon Characters

18−Hoon source files are composed almost entirely of the [printable ASCII characters](https://en.wikipedia.org/wiki/ASCII%23Printable_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.

18+Hoon source files are composed almost entirely of the [printable ASCII characters](https://en.wikipedia.org/wiki/ASCII%23Printable_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.

20```

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

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

24−> 'You can put ½ in single quotes too.'

24+> 'You can put ½ in single quotes, too.'

25−'You can put ½ in single quotes too.'

25+'You can put ½ in single quotes, too.'

27> "Some UTF-8: ἄλφα"

28"Some UTF-8: ἄλφα"

@@ -30,7 +30,7 @@ Hoon source files are composed almost entirely of the [printable ASCII character

31### Reading Hoon Aloud

33−Hoon code makes heavy use of non-alphanumeric symbols. Reading off code aloud using the proper names of ASCII symbols is tedious, so we've mapped syllables to symbols:

33+Hoon code makes heavy use of non-alphanumeric symbols. Reading off code aloud using the proper names of ASCII symbols is tedious, so we’ve mapped syllables to symbols:

35```

36ace [1 space] gap [>1 space, nl] pat @

@@ -47,25 +47,25 @@ fas / pam &

47gal < par )

48```

50−Learning and using these names of non-alphanumeric symbols is entirely optional; you can become an expert Hoon programmer without them. Many Hoon programmers find them helpful, however, particularly when talking to someone else who knows them.

50+Learning and using these names of non-alphanumeric symbols is entirely optional; you can become an expert Hoon programmer without them. Many Hoon programmers find them helpful, however, particularly when talking to someone else who knows them.

52−Note that the list includes two separate whitespace forms: `ace` for a single space; `gap` is either 2+ spaces or a newline. In Hoon, the only whitespace significance is the distinction between `ace` and `gap` -- i.e., the distinction between one space and more than one.

52+Note that the list includes two separate whitespace forms: `ace` for a single space; `gap` is either 2+ spaces or a newline. In Hoon, the only whitespace significance is the distinction between `ace` and `gap` -- i.e., the distinction between one space and more than one.

54## Expressions of Hoon

56−An [expression](https://en.wikipedia.org/wiki/Expression_%28computer_science%29 ) is a combination of characters that the language interprets and evaluates as producing a value. Hoon programs are made up entirely of expressions.

56+An [expression](https://en.wikipedia.org/wiki/Expression_%28computer_science%29 ) is a combination of characters that the language interprets and evaluates as producing a value. Hoon programs are made up entirely of expressions.

58−Hoon expressions can be either basic or complex. Basic expressions of Hoon are fundamental, meaning that they can't be broken down into smaller expressions. Complex expressions are made up of smaller expressions (which are called **subexpressions**).

58+Hoon expressions can be either basic or complex. Basic expressions of Hoon are fundamental, meaning that they can’t be broken down into smaller expressions. Complex expressions are made up of smaller expressions (which are called **subexpressions**).

60−There are many categories of Hoon expressions: [noun](/docs/glossary/noun/) literals, wing expressions, type expressions, and rune expressions. Let's go over each.

60+There are many categories of Hoon expressions: [noun](/docs/glossary/noun/) literals, wing expressions, type expressions, and rune expressions. Let’s go over each.

62### Noun Literals

64−A noun is either an [atom](/docs/glossary/atom/) or a cell. An [atom](/docs/glossary/atom/) is an unsigned integer and a cell is a pair of nouns.

64+A noun is either an [atom](/docs/glossary/atom/) or a cell. An [atom](/docs/glossary/atom/) is an unsigned integer and a cell is a pair of nouns.

66−There are [literal](https://en.wikipedia.org/wiki/Literal_%28computer_programming%29 ) expressions for each kind of noun. A noun literal is just a notation for representing a fixed noun value.

66+There are [literal](https://en.wikipedia.org/wiki/Literal_%28computer_programming%29 ) expressions for each kind of noun. A noun literal is just a notation for representing a fixed noun value.

68−We start with atom literals. Each of these is a basic expression of Hoon that evaluates to itself. Examples:

68+We start with atom literals. Each of these is a basic expression of Hoon that evaluates to itself. Examples:

70```

71> 1

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

84~zod

85```

87−Recall from [Lesson 1.2](@/docs/tutorials/hoon/nouns.md) 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.1](@/docs/tutorials/hoon/atoms-auras-and-simple-cell-types.md).

87+Recall from [Lesson 1.2](@/docs/tutorials/hoon/nouns.md) 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.1](@/docs/tutorials/hoon/atoms-auras-and-simple-cell-types.md).

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

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

91```

92> [6 7]

@@ -102,7 +102,7 @@ Cell literals can be written in Hoon using `[ ]`. Cell literals are complex, be

102[123 [~zod ~ten] .1.2837]

103```

104

105−You can also put complex expressions inside square brackets to make a cell. These are valid expressions but they aren't cell literals, naturally:

105+You can also put complex expressions inside square brackets to make a cell. These are valid expressions but they aren’t cell literals, naturally:

106

107```

108> [(add 22 33) (mul 22 33)]

@@ -111,9 +111,9 @@ You can also put complex expressions inside square brackets to make a cell. The

111

112### Wings

113

114−A wing expression is a series of limb expressions separated by `.`. A deeper explanation can be found on the [wing](@/docs/reference/hoon-expressions/limb/wing.md) and [limb](@/docs/reference/hoon-expressions/limb/limb.md) reference pages.

114+A wing expression is a series of limb expressions separated by `.`. A deeper explanation can be found on the [wing](@/docs/reference/hoon-expressions/limb/wing.md) and [limb](@/docs/reference/hoon-expressions/limb/limb.md) reference pages.

115

116−Let's start with the base case: a single limb. A limb expression is a trivial wing expression -- there is only one limb in the series. Some one-limb wings:

116+Let’s start with the base case: a single limb. A limb expression is a trivial wing expression -- there is only one limb in the series. Some one-limb wings:

117

118- `+2`

119- `-`

@@ -124,9 +124,9 @@ Let's start with the base case: a single limb. A limb expression is a trivial w

124- `add`

125- `mul`

126

127−As a special limb we also have `$`. This is the name of the [arm](/docs/glossary/arm/) in special one-armed [cores](/docs/glossary/core/) called "gates". (We'll cover the role of `$` in [Lesson 1.4](@/docs/tutorials/hoon/gates.md).)

127+As a special limb we also have `$`. This is the name of the [arm](/docs/glossary/arm/) in special one-armed [cores](/docs/glossary/core/) called “gates”. (We’ll cover the role of `$` in [Lesson 1.4](@/docs/tutorials/hoon/gates.md).)

128

129−Wing expressions with multiple limbs are complex expressions. Examples:

129+Wing expressions with multiple limbs are complex expressions. Examples:

130

131- `+2.+3.+4`

132- `-.+.+`

@@ -139,29 +139,29 @@ Wing expressions with multiple limbs are complex expressions. Examples:

139

140### Type Expressions

141

142−Hoon is a statically typed language. You'll learn more about the type system later in the chapter. For now, just know that Hoon's type system uses special symbols to indicate certain fundamental types: `~` (null), `*` (noun), `@` (atom), `^` (cell), and `?` (flag). Each of these symbols can be used as a stand-alone expression of Hoon. In the case of `@` there may be a series of letters following it, to indicate an atom aura; e.g., `@s`, `@rs`, `@tas`, and `@tD`.

142+Hoon is a statically typed language. You’ll learn more about the type system later in the chapter. For now, just know that Hoon’s type system uses special symbols to indicate certain fundamental types: `~` (null), `*` (noun), `@` (atom), `^` (cell), and `?` (flag). Each of these symbols can be used as a stand-alone expression of Hoon. In the case of `@` there may be a series of letters following it, to indicate an atom aura; e.g., `@s`, `@rs`, `@tas`, and `@tD`.

143

144−They may also be put in brackets to indicate compound types, e.g., `[@ ^]`, `[@ud @sb]`, `[[? *] ^]`. (Technically these expressions don't _always_ indicate compound types. In certain contexts they're interpreted in a different way. We'll address this variation of meaning in [Lesson 2.3](@/docs/tutorials/hoon/structures-and-complex-types.md).)

144+They may also be put in brackets to indicate compound types, e.g., `[@ ^]`, `[@ud @sb]`, `[[? *] ^]`. (Technically these expressions don’t _always_ indicate compound types. In certain contexts they’re interpreted in a different way. We’ll address this variation of meaning in [Lesson 2.3](@/docs/tutorials/hoon/structures-and-complex-types.md).)

145

146### Rune Expressions

147

148−A **rune** is just a pair of ASCII characters (a digraph). You've already seen some runes in Chapter 1: `|=`,`|%`, and `|_`. We usually pronounce runes by combining their characters' names, e.g.: 'ket-hep' for `^-`, 'bar-tis' for `|=`, and 'bar-cen' for `|%`. As stated previously, these names are entirely optional.

148+A **rune** is just a pair of ASCII characters (a digraph). You’ve already seen some runes in Chapter 1: `|=`,`|%`, and `|_`. We usually pronounce runes by combining their characters’ names, e.g.: “ket-hep” for `^-`, “bar-tis” for `|=`, and “bar-cen” for `|%`. As stated previously, these names are entirely optional.

149

150−Expressions with a rune at the beginning are rune expressions. Most runes are used at the beginning of a complex expression, but there are exceptions. For example, the runes `--` and `==` are used at the end of certain expressions.

150+Expressions with a rune at the beginning are rune expressions. Most runes are used at the beginning of a complex expression, but there are exceptions. For example, the runes `--` and `==` are used at the end of certain expressions.

151

152−Runes 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.

152+Runes 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.

153

154−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/_index.md). Nevertheless, there are some general principles that hold of all rune expressions.

154+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/_index.md). Nevertheless, there are some general principles that hold of all rune expressions.

155

156−Runes generally do not need to be closed. In other languages you'll see an abundance of terminators, such as opening and closing parentheses, and this way of doing this is largely absent from Urbit. That's because all runes take a fixed number of children. Children can themselves be runes (with more children), and Hoon programs work by chaining through these series of children until a value -- not another rune -- is arrived at. This makes Hoon code nice and neat to look at.

156+Runes generally do not need to be closed. In other languages you’ll see an abundance of terminators, such as opening and closing parentheses, and this way of doing this is largely absent from Urbit. That’s because all runes take a fixed number of children. Children can themselves be runes (with more children), and Hoon programs work by chaining through these series of children until a value -- not another rune -- is arrived at. This makes Hoon code nice and neat to look at.

157

158−#### Tall and Flat Forms

158+#### Tall and Wide Forms

159

160−There are two rune syntax forms: **tall** and **flat**. Tall form is usually used for multi-line expressions, and flat form is used for one-line expressions. Most runes can be used in either of tall or flat forms. Tall form expressions may contain flat form subexpressions, but flat form expressions may not contain tall form.

160+There are two rune syntax forms: **tall** and **wide**. Tall form is usually used for multi-line expressions, and wide form is used for one-line expressions. Most runes can be used in either of tall or wide forms. Tall form expressions may contain wide form subexpressions, but wide form expressions may not contain tall form.

161

162−The spacing rules differ in the two forms. In tall form, each rune and subexpression must be separated from the others by a `gap` -- that is, by two or more spaces, or a line break. In flat form the rune is immediately followed by parentheses `( )`, and the various subexpressions inside the parentheses must be separated from the others by an `ace` -- that is, by a single space.

162+The spacing rules differ in the two forms. In tall form, each rune and subexpression must be separated from the others by a `gap` -- that is, by two or more spaces, or a line break. In wide form the rune is immediately followed by parentheses `( )`, and the various subexpressions inside the parentheses must be separated from the others by an `ace` -- that is, by a single space.

163

164−Seeing an example will help you understand the difference. The `:-` rune is used to produce a cell. Accordingly, it is followed by two subexpressions: the first defines the head of the cell, and the second defines the tail. Here are three different ways to write a `:-` expression in tall form:

164+Seeing an example will help you understand the difference. The `:-` rune is used to produce a cell. Accordingly, it is followed by two subexpressions: the first defines the head of the cell, and the second defines the tail. Here are three different ways to write a `:-` expression in tall form:

165

166```

167> :- 11 22

@@ -177,22 +177,22 @@ Seeing an example will help you understand the difference. The `:-` rune is use

177[11 22]

178```

179

180−These all do the same thing. The first example shows that, if you want to, you can write 'tall' form code on a single line. Notice that there are two spaces between the `:-` rune and `11`, and also between `11` and `22`. This is the minimum spacing necessary between the various parts of a tall form expression -- any fewer will result in a syntax error.

180+These all do the same thing. The first example shows that, if you want to, you can write tall form code on a single line. Notice that there are two spaces between the `:-` rune and `11`, and also between `11` and `22`. This is the minimum spacing necessary between the various parts of a tall form expression -- any fewer will result in a syntax error.

181

182−Usually one or more line breaks are used to break up a tall form expression. This is especially useful when the subexpressions are themselves long stretches of code. The same `:-` expression in flat-form is:

182+Usually one or more line breaks are used to break up a tall form expression. This is especially useful when the subexpressions are themselves long stretches of code. The same `:-` expression in wide form is:

183

184```

185> :-(11 22)

186[11 22]

187```

188

189−This is the preferred way to write an expression on a single line. The rune itself is followed by a set of parentheses, and the subexpressions inside are separated by a single space. Any more spacing than that results in a syntax error.

189+This is the preferred way to write an expression on a single line. The rune itself is followed by a set of parentheses, and the subexpressions inside are separated by a single space. Any more spacing than that results in a syntax error.

190

191−Nearly all rune expressions can be written in either form, but there are exceptions. `|%` and `|_` expressions, for example, can only be written in tall form. (Those are a bit too complicated to fit comfortably on one line anyway.)

191+Nearly all rune expressions can be written in either form, but there are exceptions. `|%` and `|_` expressions, for example, can only be written in tall form. (Those are a bit too complicated to fit comfortably on one line anyway.)

192

193#### Nesting Runes

194

195−Since runes take a fixed number of children, one can visualize how Hoon expressions are built by thinking of each rune being followed by a series of boxes to be filled - one for each of its children. Let us illustrate this with the `:-` rune.

195+Since runes take a fixed number of children, one can visualize how Hoon expressions are built by thinking of each rune being followed by a series of boxes to be filled -- one for each of its children. Let us illustrate this with the `:-` rune.

196

197![](https://media.urbit.org/docs/hoon-syntax/cell1.png)

198

@@ -204,7 +204,7 @@ This, of course, evaluates to the cell `[2 3]`. This next figure corresponds to

204

205![](https://media.urbit.org/docs/hoon-syntax/cell3.png)

206

207−This evaluates to `[[2 3] 4]`, and we can think of the second `:-` as being "nested" inside of the first `:-`.

207+This evaluates to `[[2 3] 4]`, and we can think of the second `:-` as being “nested” inside of the first `:-`.

208

209What Hoon expression does the following figure correspond to, and what does it evaluate to?

210

@@ -213,17 +213,17 @@ What Hoon expression does the following figure correspond to, and what does it e

213Right. This represents the Hoon expression `:- 2 :- 3 4`,

214and evaluates to `[2 [3 4]]`. Remember, though, that if you input this into dojo it will print as `[2 3 4]`.

215

216−Thinking in terms of these "LEGO block" diagrams, as well as the more literal binary tree diagrams utilized in [Lesson 1.2](@/docs/tutorials/hoon/nouns.md), can be a helpful learning and debugging tactic.

216+Thinking in terms of these “LEGO block” diagrams, as well as the more literal binary tree diagrams utilized in [Lesson 1.2](@/docs/tutorials/hoon/nouns.md), can be a helpful learning and debugging tactic.

217

218−##### Exercise 1.3.a.

218+##### Exercise 1.3a

219

220Draw binary trees corresponding to the above figures. Determine a one-to-one correspondence between linearly ordered nested boxes (i.e. what is depicted in the above figures) and binary trees. You will need to make use of the convention `[a [b c]] = [a b c]`.

221

222#### Irregular Forms

223

224−Some runes are used so frequently that they have irregular counterparts that are easier to write and which mean precisely the same thing. Irregular rune syntax is hence a form of [syntactic sugar](https://en.wikipedia.org/wiki/Syntactic_sugar). All irregular rune syntax is flat. (It follows from this that all tall form expressions are regular.)

224+Some runes are used so frequently that they have irregular counterparts that are easier to write and which mean precisely the same thing. Irregular rune syntax is hence a form of [syntactic sugar](https://en.wikipedia.org/wiki/Syntactic_sugar). All irregular rune syntax is wide. (It follows from this that all tall form expressions are regular.)

225

226−Let's look at another example. The `.=` rune takes two subexpressions, evaluates them, and tests the results for equality. If they're equal it produces `%.y` for 'yes'; otherwise `%.n` for 'no'. In tall form:

226+Let’s look at another example. The `.=` rune takes two subexpressions, evaluates them, and tests the results for equality. If they’re equal it produces `%.y` for “yes”; otherwise `%.n` for “no”. In tall form:

227

228```

229> .= 22 11

@@ -234,7 +234,7 @@ Let's look at another example. The `.=` rune takes two subexpressions, evaluate

234%.y

235```

236

237−And in flat form:

237+And in wide form:

238

239```

240> .=(22 11)

@@ -254,7 +254,7 @@ The irregular form of the `.=` rune is just `=( )`:

254%.y

255```

256

257−The examples above have another irregular form: `(add 11 11)`. This is the irregular form of `%+`, which calls a [gate](/docs/glossary/gate/) (i.e., a Hoon function) with two arguments for the sample.

257+The examples above have another irregular form: `(add 11 11)`. This is the irregular form of `%+`, which calls a [gate](/docs/glossary/gate/) (i.e., a Hoon function) with two arguments for the sample.

258

259```

260> %+ add 11 11

@@ -283,7 +283,7 @@ You can find other irregular forms in the irregular expression [reference docume

283

284### Expressions That Are Only Irregular

285

286−There are certain irregular expressions that aren't syntactic sugar for regular form equivalents -- they're solely irregular. There isn't much in general that can be said about these because they're all different, but we can look at some examples.

286+There are certain irregular expressions that aren’t syntactic sugar for regular form equivalents -- they’re solely irregular. There isn’t much in general that can be said about these because they’re all different, but we can look at some examples.

287

288Below we use the `` ` `` symbol to create a cell whose head is null, `~`.

289

@@ -319,9 +319,9 @@ To see other irregular expressions, check the irregular expression [reference do

319

320## The Standard Library

321

322−The Hoon standard library is a compilation of generally useful Hoon gates (functions). You've seen these already: in expressions like `(add 11 11)`, `add` is a function from the standard library.

322+The Hoon standard library is a compilation of generally useful Hoon gates (functions). You’ve seen these already: in expressions like `(add 11 11)`, `add` is a function from the standard library.

323

324−It's important to know about standard library functions, because they make certain tasks much easier, and spare you from having to write the code itself. If you did not use the `add` library function, for example, you would have to write out code like this every time you wanted to find the sum of two numbers:

324+It’s important to know about standard library functions, because they make certain tasks much easier, and spare you from having to write the code itself. If you did not use the `add` library function, for example, you would have to write out code like this every time you wanted to find the sum of two numbers:

325

326```hoon

327++ add

@@ -336,12 +336,12 @@ Standard library functions are often built with other standard library functions

336

337## Reference Materials

338

339−The Hoon syntax can be intimidating for the uninitiated, so it's good to remember where you can look up expressions. The [reference section](@/docs/reference/_index.md) itself is a good place to find the reference materials that you need. These children sections are likely to be useful:

339+The Hoon syntax can be intimidating for the uninitiated, so it’s good to remember where you can look up expressions. The [Reference](@/docs/reference/_index.md) section itself is a good place to find the materials that you need. These children sections are likely to be useful:

340

341- The [Runes](@/docs/reference/hoon-expressions/rune/_index.md) page will show you how to use any Hoon rune.

342−- The [Cheat sheet](@/docs/reference/cheat-sheet.md) is a more compact place to look up rune expressions.

342+- The [Cheat Sheet](@/docs/reference/cheat-sheet.md) is a more compact place to look up rune expressions.

343−- The [Standard library](@/docs/reference/library/table-of-contents.md) section has its sub-pages arranged by category. So arithmetic functions, for example, are all found on the same page.

343+- The [Standard Library](@/docs/reference/library/table-of-contents.md) section has its sub-pages arranged by category. So arithmetic functions, for example, are all found on the same page.

344−- The [Hoon Style Guide](@/docs/tutorials/hoon/style.md) will show you how to write your Hoon code so that it's idiomatic and easily understood by others.

344+- The [Hoon Style Guide](@/docs/tutorials/hoon/style.md) will show you how to write your Hoon code so that it’s idiomatic and easily understood by others.

345

346### Debugging

347

@@ -349,8 +349,8 @@ When you have an error in your Hoon code, one of two things can happen. Either t

349

350There are a couple useful runes associated with debugging:

351

352−`!:` (zapcol), if written at the top of a Hoon file, turns on a full debugging stack-trace. It's good practice to use whenever you're learning.

352+`!:` (zapcol), if written at the top of a Hoon file, turns on a full debugging stack-trace. It’s good practice to use whenever you’re learning.

353

354`~&` (sigpam) is used to print its argument every time that argument executes. So, if you wanted to see how many times your program executed `foo`, you would write `foo bar`. Then, when your program runs, it will print `foo` on a new line of output every time the program comes across it by recursion.

355

356−But there are more. Check out the aforementioned [troubleshooting](@/docs/tutorials/hoon-errors.md) page to see other handy debugging runes and how to use them.

356+But there are more. Check out the aforementioned [Troubleshooting](@/docs/tutorials/hoon-errors.md) page to see other handy debugging runes and how to use them.

tutorials/hoon/list-of-numbers.md+11−11

@@ -20,11 +20,11 @@ Below is a simple Hoon program that takes a single number `n` from the user as i

20$(count (add 1 count)) :: 8

21```

23−As we mentioned in the previous lesson, the easiest way to use such a program is to run it as a _generator_. Mount your desk `|mount %` (if you didn't do it before), saving a file in the `/home/gen` directory of your ship and commiting these changes `|commit %home` allows you to run it from your ship's Dojo (command line) as a generator. Save the above code there as `list.hoon`. Now you can run it in the Dojo as so:

23+As we mentioned in the previous lesson, the easiest way to use such a program is to run it as a _generator_. Mount your desk `|mount %` (if you didn't do it before), saving a file in the `/home/gen` directory of your ship and commiting these changes `|commit %home` allows you to run it from your ship's Dojo (command line) as a generator. Save the above code there as `list.hoon`. Now you can run it in the Dojo with the command below (remember, without the `>`):

25−`~your-ship:> +list 5`

25+`> +list 5`

27−Try it! You can choose any natural number to put after `+list`, but it can't be zero or blank. The `+` lets the Dojo know that it's looking for a generator with the name that follows. You don't write out the `.hoon` part of the file name when running it in the Dojo.

27+Try it! You can choose any natural number to put after `+list`, but it can't be `0` or blank. The `+` lets the Dojo know that it's looking for a generator with the name that follows. You don't write out the `.hoon` part of the file name when running it in the Dojo.

29But what do all these squiggly symbols in the program _do_? It probably isn't immediately clear. Let's go through each component of this code.

@@ -42,7 +42,7 @@ In our example program, we use comments with line numbers for convenient referen

43There's a few things going on in our first line. The first part of it, `|=`, is a kind of **rune**. Runes are the building blocks of all Hoon code, represented as a pair of non-alphanumeric ASCII characters. Runes form expressions; runes are used how keywords are used in other languages. In other words, all computations in Hoon ultimately require runes. Runes and other Hoon expressions are all separated from one another by either two spaces or a line break.

45−All runes take a fixed number of "children." Children can themselves be runes with children, and Hoon programs work by chaining through these until a value -- not another rune -- is arrived at. For this reason, we very rarely need to close expressions. Keep this scheme in mind when examining Hoon code.

45+All runes take a fixed number of "children". Children can themselves be runes with children, and Hoon programs work by chaining through these until a value -- not another rune -- is arrived at. For this reason, we very rarely need to close expressions. Keep this scheme in mind when examining Hoon code.

47The specific purpose of the `|=` rune is to create a **gate**. A [gate](/docs/glossary/gate/) is what would be called a function in other languages: it takes an input, performs a specified computation, and then produces an output.

@@ -58,7 +58,7 @@ Our program is simple, so the _entire program_ is the gate that's being created

59This line begins with the `=/` rune, which stores a value with a name and specifies its type. It takes three children.

61−`count=@` (the first child) stores `1` (the second child) as `count` and as specifies that has the `@` type.

61+`count=@` (the first child) stores `1` (the second child) as `count` and specifies that it has the `@` type.

63We're using `count` to keep track of what numbers we're including in the list we're building. We'll use it later in the program.

@@ -87,11 +87,11 @@ In this case, the rune specifies that our gate's output must be `(list @)` -- th

87 ~

88```

90−`?:` is a rune that evaluates whether its first child is true or false. If that child is true, the program branches to the second child. If it's false, it branches to the third child. `?:` takes three children.

90+`?:` is a rune that evaluates whether its first child is `true` or `false`. If that child is `true`, the program branches to the second child. If it's `false`, it branches to the third child. `?:` takes three children.

92−`=(end count)` checks if the user's input equals to the `count` value that we're incrementing to build the list. If these values are equal, we want to end the program, because our list has been built out to where it needs to be. Note that this expression is, in fact, a rune expression, just written a different way than you've seen so far. `=(end count)` is an _irregular form_ of `.= end count`, different in looks but identical in operation. `.=` is a rune that checks for the equality of its two children, and produces a "true" or "false" based on what it finds.

92+`=(end count)` checks if the user's input equals to the `count` value that we're incrementing to build the list. If these values are equal, we want to end the program, because our list has been built out to where it needs to be. Note that this expression is, in fact, a rune expression, just written a different way than you've seen so far. `=(end count)` is an _irregular form_ of `.= end count`, different in looks but identical in operation. `.=` is a rune that checks for the equality of its two children, and produces a `true` or `false` based on what it finds.

94−`~` simply represents the "null" value. The program branches here if on line 5 it finds that `end` equals `count`. Lists in Hoon always end with `~`, so we need this to be the last thing we put in our list.

94+`~` simply represents the `null` value. The program branches here if on line 5 it finds that `end` equals `count`. Lists in Hoon always end with `~`, so we need this to be the last thing we put in our list.

96## Line 7

@@ -105,15 +105,15 @@ In our case, `:- count` creates a cell out of whatever value is stored in `coun

105$(count (add 1 count))

106```

107

108−The above code is, once again, a compact way of writing a rune expression. All you need to know is that this line of code restarts the program at `|-`, except with the value stored in `count` incremented by 1. The construction of `(count (add 1 count))` tells the computer, "replace the value of count with count+1".

108+The above code is, once again, a compact way of writing a rune expression. All you need to know is that this line of code restarts the program at `|-`, except with the value stored in `count` incremented by `1`. The construction of `(count (add 1 count))` tells the computer, "replace the value of `count` with `count+1`".

109

110−You'll notice that we use an unfamiliar word here: `add`. Unlike `count` and `end`, `add` is not defined anywhere in our program. That's because it's a gate that's predefined in the Hoon **standard library**. The standard library is filled with pre-defined gates that are generally useful, and these gates can be used just like something that you defined in your own program. You can see this gate, and other mathematical operators, in [section 1a](@/docs/reference/library/1a.md) of the standard-library documentation.

110+You'll notice that we use an unfamiliar word here: `add`. Unlike `count` and `end`, `add` is not defined anywhere in our program. That's because it's a gate that's predefined in the Hoon **standard library**. The standard library is filled with pre-defined gates that are generally useful, and these gates can be used just like something that you defined in your own program. You can see this gate, and other mathematical operators, in [section 1a](@/docs/reference/library/1a.md) of the standard library documentation.

111

112## Explanation

113

114If you aren't clear on how the program is building the list, that's okay.

115

116−Our program works by having each iteration of the list creating a cell. In each of these cells, the head -- the cell's first position -- is filled with the current-iteration value of `count`. The tail of the cell, its second position, is filled with _the product of a new iteration of our code_ that starts at `|-`. This iteration will itself create another cell, the head of which will be filled by the incremented value of `count`, and the tail of which will start another iteration. This process continues until `?:` branches to `~` (null). When that happens, the list is terminated and the program doesn't have anything else to do, so it ends. So, a built-out list of nested cells can be visualized like this:

116+Our program works by having each iteration of the list creating a cell. In each of these cells, the head -- the cell's first position -- is filled with the current-iteration value of `count`. The tail of the cell, its second position, is filled with _the product of a new iteration of our code_ that starts at `|-`. This iteration will itself create another cell, the head of which will be filled by the incremented value of `count`, and the tail of which will start another iteration. This process continues until `?:` branches to `~` (`null`). When that happens, the list is terminated and the program doesn't have anything else to do, so it ends. So, a built-out list of nested cells can be visualized like this:

117

118```

119 [1 [2 [3 [4 ~]]]]

tutorials/hoon/lists.md+51−34

@@ -5,11 +5,9 @@ template = "doc.html"

5aliases = ["/docs/learn/hoon/hoon-tutorial/lists/"]

6+++

8−# Lists

9−

10A **list** is a type of [noun](/docs/glossary/noun/) that you'll frequently encounter when reading and writing Hoon. A list can be thought of as an ordered arrangement of zero or more elements terminated by a `~` (null).

8A **list** is a type of [noun](/docs/glossary/noun/) that you'll frequently encounter when reading and writing Hoon. A list can be thought of as an ordered arrangement of zero or more elements terminated by a `~` (null).

12−So a list can be either null or non-null. When the list contains only `~` and no items, it's the null list. Most lists are, however, non-null lists, which have items preceding the `~`. Non-null lists, called _lests_, are cells in which the head is the first list item, and the tail is the rest of the list. The tail is itself a list, and if such a list is also non-null, the head of this sub-list is the second item in the greater list, and so on. To illustrate, let's look at a list `[1 2 3 4 ~]` with the cell-delineating brackets left in:

10+So a list can be either null or non-null. When the list contains only `~` and no items, it's the null list. Most lists are, however, non-null lists, which have items preceding the `~`. Non-null lists, called _lests_, are cells in which the head is the first list item, and the tail is the rest of the list. The tail is itself a list, and if such a list is also non-null, the head of this sublist is the second item in the greater list, and so on. To illustrate, let's look at a list `[1 2 3 4 ~]` with the cell-delineating brackets left in:

14`[1 [2 [3 [4 ~]]]]`

12`[1 [2 [3 [4 ~]]]]`

@@ -44,7 +42,7 @@ Let's make a list whose items are of the `@t` string type:

44<|Urbit will rescue the internet|>

42<|Urbit will rescue the internet|>

45```

43```

47−The head of a list has the face `i` and the tail has the face `t`. (For the sake of neatness, these faces aren't shown by the Hoon pretty printer.) To use the `i` and `t` faces of a list, you must first prove that the list is non-null by using the conditional family of runes, `?`:

45+The head of a list has the face `i` and the tail has the face `t`. (For the sake of neatness, these faces aren't shown by the Hoon pretty printer.) To use the `i` and `t` faces of a list, you must first prove that the list is non-null by using the conditional family of runes, `?`:

49```

47```

50> =>(b=`(list @)`[1 2 3 4 5 ~] i.b)

48> =>(b=`(list @)`[1 2 3 4 5 ~] i.b)

@@ -58,15 +56,15 @@ find-fork-d

58~[2 3 4 5]

56~[2 3 4 5]

59```

57```

61−It's important to note that performing tests like `?~ mylist` will actually transform `mylist` into a `lest`, a non-null list. Because `lest` is a different type than `list`, performing such tests can come back to bite you later in non-obvious ways when you try to use some standard library functions meant for `list`s.

59+It's important to note that performing tests like `?~ mylist` will actually transform `mylist` into a `lest`, a non-null list. Because `lest` is a different type than `list`, performing such tests can come back to bite you later in non-obvious ways when you try to use some standard library functions meant for lists.

63−You can construct lists of any type. `(list @)` indicates a list of atoms, `(list ^)` indicates a list of cells, `(list [@ ?])` indicates a list of cells whose head is an atom and whose tail is a flag, etc.

61+You can construct lists of any type. `(list @)` indicates a list of atoms, `(list ^)` indicates a list of cells, `(list [@ ?])` indicates a list of cells whose head is an atom and whose tail is a flag, etc.

65## Tapes and Cords

63## Tapes and Cords

67−While a list can be of any type, there are some special types of lists that are built into Hoon. The tape is the most common example.

65+While a list can be of any type, there are some special types of lists that are built into Hoon. The `tape` is the most common example.

69−Hoon has two kinds of strings: cords and tapes. Cords are atoms with aura `@t`, and they're pretty-printed between `''` marks.

67+Hoon has two kinds of strings: cords and tapes. Cords are atoms with aura `@t`, and they're pretty-printed between `''` marks.

71```

69```

72> 'this is a cord'

70> 'this is a cord'

@@ -98,9 +96,9 @@ You can also use the words `cord` and `tape` for casting:

99## List Functions in the Hoon Standard Library

97## List Functions in the Hoon Standard Library

100

101−Lists are a commonly used data structure. Accordingly, there are several functions in the [Hoon standard library](/docs/reference/library/) intended to make lists easier to use.

99+Lists are a commonly used data structure. Accordingly, there are several functions in the [Hoon standard library](/docs/reference/library/) intended to make lists easier to use.

102

100

103−For a complete list of these functions, check out the standard library reference for lists [here](/docs/reference/library/2b/). Here we'll look at a few of these functions.

101+For a complete list of these functions, check out the standard library reference for lists [here](/docs/reference/library/2b/). Here we'll look at a few of these functions.

104

102

105### `flop`

103### `flop`

106

104

@@ -119,18 +117,18 @@ The `flop` function takes a list and returns it in reverse order:

119

117

120#### `flop` Exercise 1.5a

118#### `flop` Exercise 1.5a

121

119

122−Without using `flop`, write a [gate](/docs/glossary/gate/) that takes a `(list @)` and returns it in reverse order. There is a solution at the bottom of this lesson.

120+Without using `flop`, write a [gate](/docs/glossary/gate/) that takes a `(list @)` and returns it in reverse order. There is a solution at the bottom of this lesson.

123

121

124### `sort`

122### `sort`

125

123

126−The `sort` function uses the 'quicksort' algorithm to sort a list. It takes a list to sort and a gate that serves as a comparator. For example, if you want to sort the list `~[37 62 49 921 123]` from least to greatest, you would pass that list along with the `lth` gate (for 'less than'):

124+The `sort` function uses the "quicksort" algorithm to sort a list. It takes a list to sort and a gate that serves as a comparator. For example, if you want to sort the list `~[37 62 49 921 123]` from least to greatest, you would pass that list along with the `lth` gate (for "less than"):

127

125

128```

126```

129> (sort ~[37 62 49 921 123] lth)

127> (sort ~[37 62 49 921 123] lth)

130~[37 49 62 123 921]

128~[37 49 62 123 921]

131```

129```

132

130

133−To sort the list from greatest to least, use the `gth` gate ('greater than') as the basis of comparison instead:

131+To sort the list from greatest to least, use the `gth` gate ("greater than") as the basis of comparison instead:

134

132

135```

133```

136> (sort ~[37 62 49 921 123] gth)

134> (sort ~[37 62 49 921 123] gth)

@@ -160,7 +158,7 @@ The `weld` function takes two lists of the same type and concatenates them:

160

158

161#### `weld` Exercise 1.5b

159#### `weld` Exercise 1.5b

162

160

163−Without using `weld`, write a gate that takes a `[(list @) (list @)]` who product is the concatenation of these two lists. There is a solution at the bottom of this lesson.

161+Without using `weld`, write a gate that takes a `[(list @) (list @)]` of which the product is the concatenation of these two lists. There is a solution at the bottom of this lesson.

164

162

165### `snag`

163### `snag`

166

164

@@ -186,7 +184,7 @@ The `snag` function takes an atom `n` and a list, and returns the `n`th item of

186'!'

184'!'

187```

185```

188

186

189−Note: there is currently a type system issue that causes some of these functions to fail when passed a list `b` after some type inference has been performed on `b`. For an illustration of the bug, let's set `b` to be a `(list @)` of `~[11 22 33 44]` in the dojo:

187+Note: there is currently a type system issue that causes some of these functions to fail when passed a list `b` after some type inference has been performed on `b`. For an illustration of the bug, let's set `b` to be a `(list @)` of `~[11 22 33 44]` in the Dojo:

190

188

191```

189```

192> =b `(list @)`~[11 22 33 44]

190> =b `(list @)`~[11 22 33 44]

@@ -213,7 +211,7 @@ You can cast `b` to `(list)` to work around this:

213

211

214#### `snag` Exercise 1.5c

212#### `snag` Exercise 1.5c

215

213

216−Without using `snag`, write a gate that returns the `n`th item of a list. There is a solution at the bottom of this lesson.

214+Without using `snag`, write a gate that returns the `n`th item of a list. There is a solution at the bottom of this lesson.

217

215

218### `oust`

216### `oust`

219

217

@@ -251,7 +249,7 @@ Without using `lent`, write a gate that takes a list and returns the number of i

251

249

252### `roll`

250### `roll`

253

251

254−The `roll` function takes a list and a gate, and accumulates a value of the list items using that gate. For example, if you want to add or multiply all the items in a list of atoms, you would use `roll`:

252+The `roll` function takes a list and a gate, and accumulates a value of the list items using that gate. For example, if you want to add or multiply all the items in a list of atoms, you would use `roll`:

255

253

256```

254```

257> (roll `(list @)`~[11 22 33 44 55] add)

255> (roll `(list @)`~[11 22 33 44 55] add)

@@ -263,7 +261,7 @@ The `roll` function takes a list and a gate, and accumulates a value of the list

263

261

264### `turn`

262### `turn`

265

263

266−The `turn` function takes a list and a gate, and returns a list of the products of applying each item of the input list to the gate. For example, to add `1` to each item in a list of atoms:

264+The `turn` function takes a list and a gate, and returns a list of the products of applying each item of the input list to the gate. For example, to add `1` to each item in a list of atoms:

267

265

268```

266```

269> (turn `(list @)`~[11 22 33 44] |=(a=@ +(a)))

267> (turn `(list @)`~[11 22 33 44] |=(a=@ +(a)))

@@ -279,7 +277,7 @@ Or to double each item in a list of atoms:

279

277

280`turn` is Hoon's version of Haskell's `map`.

278`turn` is Hoon's version of Haskell's `map`.

281

279

282−We can rewrite the Caesar cipher program using `turn`:

280+We can rewrite the [Caesar cipher](https://en.wikipedia.org/wiki/Caesar_cipher) program using `turn`:

283

281

284```hoon

282```hoon

285|= [a=@ b=tape]

283|= [a=@ b=tape]

@@ -301,49 +299,60 @@ c

301

299

302## Using `hoon.hoon` to Learn Hoon

300## Using `hoon.hoon` to Learn Hoon

303

301

304−The Hoon standard library and compiler are written in Hoon. At this point, you know enough Hoon to be able to explore the standard library portions of `hoon.hoon` and find more functions relevant to lists. [Look around in section `2b` (and elsewhere)](/docs/reference/library/2b/)

302+The Hoon standard library and compiler are written in Hoon. At this point, you know enough Hoon to be able to explore the standard library portions of `hoon.hoon` and find more functions relevant to lists. Look around in [section 2b](/docs/reference/library/2b/) (and elsewhere).

305

303

306## Additional Exercises

304## Additional Exercises

307

305

308#### Exercise 1.5e

306#### Exercise 1.5e

307+

309−Without entering these expressions into the dojo, what are the products of the following expressions?

308+Without entering these expressions into the Dojo, what are the products of the following expressions?

309+

310```

311> (lent ~[1 2 3 4 5])

312```

313+

313```

314```

314> (lent ~[~[1 2] ~[1 2 3] ~[2 3 4]])

315> (lent ~[~[1 2] ~[1 2 3] ~[2 3 4]])

315```

316```

317+

316```

318```

317> (lent ~[1 2 (weld ~[1 2 3] ~[4 5 6])])

319> (lent ~[1 2 (weld ~[1 2 3] ~[4 5 6])])

318```

320```

319

321

320#### Exercise 1.5f

322#### Exercise 1.5f

323+

321First, bind these faces.

324First, bind these faces.

325+

322```

326```

323> =b ~['moon' 'planet' 'star' 'galaxy']

327> =b ~['moon' 'planet' 'star' 'galaxy']

324> =c ~[1 2 3]

328> =c ~[1 2 3]

325```

329```

330+

326−Then determine whether the following dojo expressions are valid, and if so, what they evaluate to.

331+Then determine whether the following Dojo expressions are valid, and if so, what they evaluate to.

332+

327```

333```

328> (weld b b)

334> (weld b b)

329```

335```

336+

330```

337```

331> (weld b c)

338> (weld b c)

332```

339```

340+

333```

341```

334> (lent (weld b c))

342> (lent (weld b c))

335```

343```

344+

336```

345```

337> (add (lent b) (lent c))

346> (add (lent b) (lent c))

338```

347```

339

348

340#### Exercise 1.5g

349#### Exercise 1.5g

341−Write a gate that takes in a list `a` and returns `%.y` if `a` is a palindrome and `%.n` otherwise. You may make use of the `flop` function.

342

350

351+Write a gate that takes in a list `a` and returns `%.y` if `a` is a palindrome and `%.n` otherwise. You may make use of the `flop` function.

343

352

344## Exercise Solutions

353## Exercise Solutions

345

354

346−#### `flop` 1.5a

355+#### 1.5a `flop`

347

356

348```hoon

357```hoon

349:: flop.hoon

358:: flop.hoon

@@ -355,14 +364,15 @@ Write a gate that takes in a list `a` and returns `%.y` if `a` is a palindrome a

355$(b [i.a b], a t.a)

364$(b [i.a b], a t.a)

356```

365```

357

366

358−Run in dojo:

367+Run in Dojo:

359

368

360```

369```

361> +flop ~[11 22 33 44]

370> +flop ~[11 22 33 44]

362~[44 33 22 11]

371~[44 33 22 11]

363```

372```

364

373

365−#### `weld` 1.5b

374+#### 1.5b `weld`

375+

366```hoon

376```hoon

367:: weld.hoon

377:: weld.hoon

368::

378::

@@ -372,14 +382,14 @@ Run in dojo:

372[i.a $(a t.a)]

382[i.a $(a t.a)]

373```

383```

374

384

375−Run in dojo:

385+Run in Dojo:

376

386

377```

387```

378> +weld [~[1 2 3] ~[3 4 5 6]]

388> +weld [~[1 2 3] ~[3 4 5 6]]

379~[1 2 3 3 4 5 6]

389~[1 2 3 3 4 5 6]

380```

390```

381

391

382−#### `snag` 1.5c

392+#### 1.5c `snag`

383

393

384```hoon

394```hoon

385:: snag.hoon

395:: snag.hoon

@@ -390,7 +400,7 @@ Run in dojo:

390$(a (dec a), b t.b)

400$(a (dec a), b t.b)

391```

401```

392

402

393−Run in dojo:

403+Run in Dojo:

394

404

395```

405```

396> +snag [0 ~[11 22 33 44]]

406> +snag [0 ~[11 22 33 44]]

@@ -400,7 +410,7 @@ Run in dojo:

40033

41033

401```

411```

402

412

403−#### `lent` 1.5d

413+#### 1.5d `lent`

404

414

405```hoon

415```hoon

406:: lent.hoon

416:: lent.hoon

@@ -413,7 +423,7 @@ Run in dojo:

413$(a t.a, b +(b))

423$(a t.a, b +(b))

414```

424```

415

425

416−Run in dojo:

426+Run in Dojo:

417

427

418```

428```

419> +lent ~[1 2 3 4 5]

429> +lent ~[1 2 3 4 5]

@@ -424,7 +434,7 @@ Run in dojo:

424

434

425#### 1.5e

435#### 1.5e

426

436

427−Run in dojo:

437+Run in Dojo:

428

438

429```

439```

430> (lent ~[1 2 3 4 5])

440> (lent ~[1 2 3 4 5])

@@ -437,27 +447,34 @@ Run in dojo:

437

447

438#### 1.5f

448#### 1.5f

439

449

440−Run in dojo:

450+Run in Dojo:

441

451

442```

452```

443> (weld b b)

453> (weld b b)

444<|moon planet star galaxy moon planet star galaxy|>

454<|moon planet star galaxy moon planet star galaxy|>

445```

455```

456+

446```

457```

447> (weld b c)

458> (weld b c)

448```

459```

460+

449This will not run because `weld` expects the elements of both lists to be of the same type.

461This will not run because `weld` expects the elements of both lists to be of the same type.

462+

450```

463```

451> (lent (weld b c))

464> (lent (weld b c))

452```

465```

466+

453This also fails for the same reason, but it is important to note that in some languages that are more lazily evaluated, such an expression would still work since it would only look at the length of `b` and `c` and not worry about what the elements were. In that case, it would return `7`.

467This also fails for the same reason, but it is important to note that in some languages that are more lazily evaluated, such an expression would still work since it would only look at the length of `b` and `c` and not worry about what the elements were. In that case, it would return `7`.

468+

454```

469```

455> (add (lent b) (lent c))

470> (add (lent b) (lent c))

4567

4717

457```

472```

473+

458We see here the correct way to find the sum of the length of two lists of unknown type.

474We see here the correct way to find the sum of the length of two lists of unknown type.

459

475

460#### 1.5g

476#### 1.5g

477+

461```hoon

478```hoon

462:: palindrome.hoon

479:: palindrome.hoon

463::

480::

@@ -465,7 +482,7 @@ We see here the correct way to find the sum of the length of two lists of unknow

465=(a (flop a))

482=(a (flop a))

466```

483```

467

484

468−Run in dojo:

485+Run in Dojo:

469

486

470```

487```

471> +palindrome "urbit"

488> +palindrome "urbit"

tutorials/hoon/nouns.md+52−45

@@ -5,11 +5,11 @@ template = "doc.html"

5aliases = ["/docs/learn/hoon/hoon-tutorial/nouns/"]

6+++

8−In Urbit, every piece of data is a [noun](/docs/glossary/noun/). In order to understand Hoon, one must first understand nouns.

8+In Urbit, every piece of data is a [noun](/docs/glossary/noun/). In order to understand Hoon, one must first understand nouns.

10## Noun Definition

12−A **noun** is either an [atom](/docs/glossary/atom/) or a cell. An **atom** is a natural number ("unsigned integer" in computer lingo) of any size, including zero. A **cell** is an [ordered pair](https://en.wikipedia.org/wiki/Ordered_pair) of nouns, usually indicated with square brackets around the nouns in question; i.e., `[a b]`, where `a` and `b` are nouns.

12+A **noun** is either an [atom](/docs/glossary/atom/) or a cell. An **atom** is a natural number ("unsigned integer" in computer lingo) of any size, including zero. A **cell** is an [ordered pair](https://en.wikipedia.org/wiki/Ordered_pair) of nouns, usually indicated with square brackets around the nouns in question; i.e., `[a b]`, where `a` and `b` are nouns.

14Here are some atoms:

@@ -28,7 +28,7 @@ All of the above are nouns.

29### Nouns as Binary Trees

31−A [binary tree](https://en.wikipedia.org/wiki/Binary_tree) has a single base node, and each node of the tree may have up to two child nodes (but it need not have any). A node without children is a 'leaf'. You can think of a noun as a binary tree whose leaves are atoms, i.e., unsigned integers. All non-leaf nodes are cells. To visualize this, consider the following representation of the noun: `[12 [17 45]]`:

31+A [binary tree](https://en.wikipedia.org/wiki/Binary_tree) has a single base node, and each node of the tree may have up to two child nodes (but it need not have any). A node without children is a "leaf". You can think of a noun as a binary tree whose leaves are atoms, i.e., unsigned integers. All non-leaf nodes are cells. To visualize this, consider the following representation of the noun: `[12 [17 45]]`:

33```

34[12 [17 45]]

@@ -39,7 +39,7 @@ A [binary tree](https://en.wikipedia.org/wiki/Binary_tree) has a single base nod

39 17 45

40```

42−Each number is an atom; each dot is a cell. Let's look at another example, this time of `[[7 13] [87 65]]`, with the cell nodes shown explicitly:

42+Each number is an atom; each dot is a cell. Let's look at another example, this time of `[[7 13] [87 65]]`, with the cell nodes shown explicitly:

44```

45 [[7 13] [87 65]]

@@ -55,9 +55,9 @@ An atom is a trivial tree of just one node; e.g., `17`.

56## Atoms

58−Atoms are unsigned integers. These are often represented by the dojo as unsigned integers in decimal notation, e.g., `17`.

58+Atoms are unsigned integers. These are often represented by the Dojo as unsigned integers in decimal notation, e.g., `17`.

60−To be sure we understand Hoon's atom notation, let's enter some atoms into the dojo:

60+To be sure we understand Hoon's atom notation, let's enter some atoms into the Dojo:

62```

63> 3

@@ -84,9 +84,9 @@ Can we add another zero?

84> 320

85```

87−It didn't work! When you tried to type that next zero and turn `320` into `3200`, the dojo actually _deleted the `0` and beeped at you_.

87+It didn't work! When you tried to type that next zero and turn `320` into `3200`, the Dojo actually _deleted the `0` and beeped at you_.

89−Isn't an atom an unsigned integer of any size? It is. But the way to represent the four-digit number `3200` is actually `3.200`:

89+Isn't an atom an unsigned integer of any size? It is. But the way to represent the four-digit number `3200` is actually `3.200`:

91```

92> 3.200

@@ -98,21 +98,21 @@ Isn't an atom an unsigned integer of any size? It is. But the way to represent

99Just think of it as "3,200", written the German way with a dot.

100

101−Why? Long numbers are difficult to read. We know this, so we group digits in threes. For some reason most programming languages don't use this marvelous innovation. Hoon does.

101+Why? Long numbers are difficult to read. We know this, so we group digits in threes. For some reason, most programming languages don't use this marvelous innovation. Hoon does.

102

103−English notation for decimals is more common than German notation. Unfortunately, dots are URL-safe and commas aren't. For reasons to be discussed in a later lesson, it's nice to have a regular syntax for atoms that's URL-safe.

103+English notation for decimals is more common than German notation. Unfortunately, dots are URL-safe and commas aren't. For reasons to be discussed in a later lesson, it's nice to have a regular syntax for atoms that's URL-safe.

104

105−As for why the dojo deleted your zero: it parses the command line as you type, and rejects any characters after the parser stops. This prevents you from entering commands or expressions that aren't well-formed.

105+As for why the Dojo deleted your zero: it parses the command line as you type, and rejects any characters after the parser stops. This prevents you from entering commands or expressions that aren't well-formed.

106

107### Atom Auras

108

109−Atoms are nothing more than unsigned integers -- natural numbers -- but it's often useful to represent an atom in a different way. This is done with an **aura**. The aura of an atom is type meta-data used by Hoon to determine how to interpret that atom. It answers the question: What type of information is this atom?

109+Atoms are nothing more than unsigned integers -- natural numbers -- but it's often useful to represent an atom in a different way. This is done with an **aura**. The aura of an atom is type meta-data used by Hoon to determine how to interpret that atom. It answers the question: What type of information is this atom?

110

111−We use auras because data isn't always represented as a positive decimal number. Sometimes we want to represent data as binary, as text, or as a negative number. Auras allow us to to use such types of data _without changing the underlying atom_.

111+We use auras because data isn't always represented as a positive decimal number. Sometimes we want to represent data as binary, as text, or as a negative number. Auras allow us to use such types of data _without changing the underlying atom_.

112

113−We won't fully explain auras and their various uses yet. Auras will be covered more comprehensively in a later lesson. For now let's just look at the various kinds of [literal syntax](https://en.wikipedia.org/wiki/Literal_%28computer_programming%29) associated with a few atom auras.

113+We won't fully explain auras and their various uses yet. Auras will be covered more comprehensively in a later lesson. For now let's just look at the various kinds of [literal syntax](https://en.wikipedia.org/wiki/Literal_%28computer_programming%29) associated with a few atom auras.

114

115−In computer science, a 'literal' is an expression that represents and evaluates to a fixed value. The default syntax of an atom literal is the German-style decimal notation, as seen above. Let's look at some other atom literal syntaxes: unsigned binary, unsigned hexadecimal, signed decimal, signed binary and hexadecimal.

115+In computer science, a "literal" is an expression that represents and evaluates to a fixed value. The default syntax of an atom literal is the German-style decimal notation, as seen above. Let's look at some other atom literal syntaxes: unsigned binary, unsigned hexadecimal, signed decimal, signed binary, and signed hexadecimal.

116

117```

118> 0b1001

@@ -140,7 +140,7 @@ In computer science, a 'literal' is an expression that represents and evaluates

140-0x9d

141```

142

143−All of the above are atoms. The underlying noun of each is just an unsigned integer, but each is written in a special syntax indicating to Hoon that the atom is to be represented in a different way. To see their values in the default atom notation, you can tell Hoon to throw away the aura information. Do this by preceding each expression above with `` `@` ``.

143+All of the above are atoms. The underlying noun of each is just an unsigned integer, but each is written in a special syntax indicating to Hoon that the atom is to be represented in a different way. To see their values in the default atom notation, you can tell Hoon to throw away the aura information. Do this by preceding each expression above with `` `@` ``.

144

145```

146> `@`0b1001

@@ -168,7 +168,7 @@ All of the above are atoms. The underlying noun of each is just an unsigned int

168313

169```

170

171−The `` `@` `` syntax is used to 'cast' a value to a raw atom, i.e., an atom without an aura. Don't worry about exactly what `` `@` `` means just yet. Casts will be explained in more detail in a later lesson. For now all you need to know is that a cast doesn't change the underlying value of the noun; it's used here only to change how the value is printed in the dojo output.

171+The `` `@` `` syntax is used to "cast" a value to a raw atom, i.e., an atom without an aura. Don't worry about exactly what `` `@` `` means just yet. Casts will be explained in more detail in a later lesson. For now all you need to know is that a cast doesn't change the underlying value of the noun; it's used here only to change how the value is printed in the Dojo output.

172

173#### Identities, Cords, and Terms

174

@@ -194,7 +194,7 @@ Urbit identities such as `~zod` and `~sorreg-namtyv` are also atoms, but of the

194~sorreg-namtyv

195```

196

197−Hoon permits the use of atoms as strings. Strings that are encoded as atoms are called **cords**. Cords are of the aura `@t`. The literal syntax of a cord is text inside a pair of single-quotes, e.g., `'Hello world!'`.

197+Hoon permits the use of atoms as strings. Strings that are encoded as atoms are called **cords**. Cords are of the aura `@t`. The literal syntax of a cord is text inside a pair of single-quotes, e.g., `'Hello world!'`.

198

199```

200> 'Howdy!'

@@ -210,7 +210,7 @@ Hoon permits the use of atoms as strings. Strings that are encoded as atoms are

21010.334.410.032.606.748.633.331.426.632

211```

212

213−Hoon also has **terms**, of the aura `@tas`. Terms are constant values that are used to tag data using the type system. These are strings preceded with a `%` and made up of lower-case letters, numbers, and hyphens, i.e., 'kebab case'. The first character after the `%` must be a letter. For example, `%a`, `%hello`, `%this-is-kebab-case123`.

213+Hoon also has **terms**, of the aura `@tas`. Terms are constant values that are used to tag data using the type system. These are strings preceded with a `%` and made up of lowercase letters, numbers, and hyphens, i.e., "kebab case". The first character after the `%` must be a letter. For example, `%a`, `%hello`, `%this-is-kebab-case123`.

214

215```

216> %howdy

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

2810x9d

282```

283

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

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

285

286You'll learn more about atoms and auras in [Lesson 2.1](@docs/tutorials/hoon/atoms-auras-and-simple-cell-types.md).

287

288## Cells

289

290−There's not much mystery about cells. The left of a cell is called the **head**, and the right is called the **tail**. Cells are typically represented in Hoon with square brackets around a pair of nouns.

290+There's not much mystery about cells. The left of a cell is called the **head**, and the right is called the **tail**. Cells are typically represented in Hoon with square brackets around a pair of nouns.

291

292```

293> [32 320]

294[32 320]

295```

296

297−In this cell `32` is the head and `320` is the tail. Cells can contain cells, and atoms of other auras as well:

297+In this cell `32` is the head and `320` is the tail. Cells can contain cells, and atoms of other auras as well:

298

299```

300> [%hello 'world!']

@@ -304,7 +304,7 @@ In this cell `32` is the head and `320` is the tail. Cells can contain cells, a

304[[%in 0xa] 'cell']

305```

306

307−I said there isn't _much_ mystery about cells, but there is a little. So far whenever we've entered a cell into the dojo, it not only returned the same cell; the cell was printed in the same way it was entered. This doesn't always happen. The dojo is obligated to evaluate the input and return the correct answer, but it doesn't have to show the result in exactly the same way:

307+I said there isn't _much_ mystery about cells, but there is a little. So far whenever we've entered a cell into the Dojo, it not only returned the same cell; the cell was printed in the same way it was entered. This doesn't always happen. The Dojo is obligated to evaluate the input and return the correct answer, but it doesn't have to show the result in exactly the same way:

308

309```

310> [6 [62 620]]

@@ -317,11 +317,11 @@ I said there isn't _much_ mystery about cells, but there is a little. So far wh

317[[6 62] 620]

318```

319

320−In the first example, the inner pair of square brackets is dropped. Why did this happen? Why is `[6 62 620]` accepted as a cell despite apparently having more than two atoms in it?

320+In the first example, the inner pair of square brackets is dropped. Why did this happen? Why is `[6 62 620]` accepted as a cell despite apparently having more than two atoms in it?

321

322−In fact, `[6 [62 620]]` and `[6 62 620]` are considered equivalent in Hoon. A cell _must_ be a pair, which means there are always exactly two nouns in it. Whenever cell brackets are omitted so that visually there appears to be more than two child nouns, it is implicitly understood that the right-most nouns constitute a cell. That is, the tail of the whole cell is assumed to be a cell of the right-most nouns.

322+In fact, `[6 [62 620]]` and `[6 62 620]` are considered equivalent in Hoon. A cell _must_ be a pair, which means there are always exactly two nouns in it. Whenever cell brackets are omitted so that visually there appears to be more than two child nouns, it is implicitly understood that the right-most nouns constitute a cell. That is, the tail of the whole cell is assumed to be a cell of the right-most nouns.

323

324−This is why `[6 [62 620]]` and `[6 62 620]` are equivalent. `[6 [62 620]]` and `[[6 62] 620]`, on the other hand, are not equivalent. If you look at them as binary trees you can see the difference:

324+This is why `[6 [62 620]]` and `[6 62 620]` are equivalent. `[6 [62 620]]` and `[[6 62] 620]`, on the other hand, are not equivalent. If you look at them as binary trees you can see the difference:

325

326```

327 [6 [62 620]] [[6 62] 620]

@@ -332,7 +332,7 @@ This is why `[6 [62 620]]` and `[6 62 620]` are equivalent. `[6 [62 620]]` and

332 62 620 6 62

333```

334

335−When the dojo pretty-prints a cell it always removes superfluous cell brackets:

335+When the Dojo pretty-prints a cell it always removes superfluous cell brackets:

336

337```

338> [[12 13] [[14 15] [16 17]]]

@@ -343,7 +343,7 @@ However, you should always remember that though cells can be presented as lists

343

344### Exercise 1.2a

345

346−Without using the dojo, assess whether each of the following pairs of nouns is equivalent. (Answers are at the bottom of the page.)

346+Without using the Dojo, assess whether each of the following pairs of nouns is equivalent. (Answers are at the bottom of the page.)

347

348```

3491. [[1 3] [6 2]] [1 3 [6 2]]

@@ -355,15 +355,15 @@ Without using the dojo, assess whether each of the following pairs of nouns is e

355

356## Noun Addresses

357

358−Nouns have a regular structure that can be exploited to give a unique **address** to each of its 'sub-nouns'. A sub-noun is a part of a noun that is itself a noun; e.g., `[6 2]` is a sub-noun of `[[1 3] [6 2]]`. We can also call these 'noun fragments'.

358+Nouns have a regular structure that can be exploited to give a unique **address** to each of its "sub-nouns". A sub-noun is a part of a noun that is itself a noun; e.g., `[6 2]` is a sub-noun of `[[1 3] [6 2]]`. We can also call these "noun fragments".

359

360−What if you want to refer to a noun fragment, and not the whole thing? For example, what if you want to refer to the `[6 2]` part of `[[1 3] [6 2]]`? One way is to use the unique address of that noun fragment.

360+What if you want to refer to a noun fragment, and not the whole thing? For example, what if you want to refer to the `[6 2]` part of `[[1 3] [6 2]]`? One way is to use the unique address of that noun fragment.

361

362−To define noun addresses we'll use recursion. The base case is trivial: address `1` of a noun is the entire noun. The generating case: if the noun at address `n` is a cell, then its head is at address `2n` and its tail is at address `2n + 1`. For example, if address `5` of some noun is a cell, then its head is at address `10` and its tail address `11`.

362+To define noun addresses we'll use recursion. The base case is trivial: address `1` of a noun is the entire noun. The generating case: if the noun at address `n` is a cell, then its head is at address `2n` and its tail is at address `2n + 1`. For example, if address `5` of some noun is a cell, then its head is at address `10` and its tail address `11`.

363

364−Address 1 of the noun `[[1 3] [6 2]]` is the whole noun: `[[1 3] [6 2]]`. The head of the noun at address `1`, `[1 3]`, is at address `2 x 1`, i.e., `2`. The tail of the noun at address `1`, `[6 2]`, is at address `(2 x 1) + 1`, i.e., `3`.

364+Address 1 of the noun `[[1 3] [6 2]]` is the whole noun: `[[1 3] [6 2]]`. The head of the noun at address `1`, `[1 3]`, is at address `2 x 1`, i.e., `2`. The tail of the noun at address `1`, `[6 2]`, is at address `(2 x 1) + 1`, i.e., `3`.

365

366−If the way this works isn't immediately clear, remember that each noun can be understood as a binary tree. The following diagram shows the address of several nodes of the tree:

366+If the way this works isn't immediately clear, remember that each noun can be understood as a binary tree. The following diagram shows the address of several nodes of the tree:

367

368```

369 1

@@ -375,7 +375,7 @@ If the way this works isn't immediately clear, remember that each noun can be un

375 14 15

376```

377

378−Let's do some examples in the dojo. We're going to use the `slot` operator, `+`, to return fragments of a noun. For any unsigned integer `n`, `+n` evaluates to the fragment at address `n`.

378+Let's do some examples in the Dojo. We're going to use the `slot` operator, `+`, to return fragments of a noun. For any unsigned integer `n`, `+n` evaluates to the fragment at address `n`.

379

380```

381> +1:[22 [33 44]]

@@ -394,7 +394,7 @@ Let's do some examples in the dojo. We're going to use the `slot` operator, `+`

39444

395```

396

397−You'll notice that we use the `:` symbol between the slot syntax and the noun. Don't worry about what this means yet; we'll explain it in another lesson. For now you can read it as the word "of": `+7:[22 [33 44]]` is "slot `7` of `[22 [33 44]]`".

397+You'll notice that we use the `:` symbol between the slot syntax and the noun. Don't worry about what this means yet; we'll explain it in another lesson. For now you can read it as the word "of": `+7:[22 [33 44]]` is "slot `7` of `[22 [33 44]]`".

398

399What happens if you ask for a fragment that doesn't exist?

400

@@ -422,7 +422,8 @@ Let's do a few more examples:

422%six

423```

424

425−For those who prefer to think in terms of binary numbers and binary trees, there is another (equivalent) way to understand noun addressing. When the noun address is expressed as a binary number, you can think of the number as indicating a tree path from the top node.

425+For those who prefer to think in terms of binary numbers and binary trees, there is another (equivalent) way to understand noun addressing. When the noun address is expressed as a binary number, you can think of the number as indicating a tree path from the top node.

426+

426

427

427As before, the root of the binary tree (i.e., the whole noun) is at address `1`. For the node of a tree at any address `b`, where `b` is a binary number, you get the address of its head by concatenating a `0` to the end of `b`; and to get its tail, concatenate a `1` to the end. For example, the head of the node at binary address `111` is at `1110`, and the tail is at `1111`.

428As before, the root of the binary tree (i.e., the whole noun) is at address `1`. For the node of a tree at any address `b`, where `b` is a binary number, you get the address of its head by concatenating a `0` to the end of `b`; and to get its tail, concatenate a `1` to the end. For example, the head of the node at binary address `111` is at `1110`, and the tail is at `1111`.

428

429

@@ -430,7 +431,7 @@ Address `1110` indicates "the head of the tail of the tail of the noun".

430

431

431### Exercise 1.2b

432### Exercise 1.2b

432

433

433−Without using the dojo, evaluate the following expressions. (Answers are at the bottom of the page.)

434+Without using the Dojo, evaluate the following expressions. (Answers are at the bottom of the page.)

434

435

435```

436```

4361. +6:[[34 54] [86 48]]

4371. +6:[[34 54] [86 48]]

@@ -442,7 +443,7 @@ Without using the dojo, evaluate the following expressions. (Answers are at the

442

443

443### Exercise 1.2c

444### Exercise 1.2c

444

445

445−Without using the dojo, for each fragment below provide the address relative to the noun `[51 52 53 54 55]`. (Answers are at the bottom of the page.)

446+Without using the Dojo, for each fragment below provide the address relative to the noun `[51 52 53 54 55]`. (Answers are at the bottom of the page.)

446

447

447```

448```

4481. 51

4491. 51

@@ -452,11 +453,11 @@ Without using the dojo, for each fragment below provide the address relative to

4525. 55

4535. 55

453```

454```

454

455

455−That's it for our basic introduction to nouns. Hit `ctrl-d` to exit your ship, or else move on to the next lesson.

456+That's it for our basic introduction to nouns. Hit `ctrl-d` to exit your ship, or else move on to the next lesson.

456

457

457### Exercise 1.2d

458### Exercise 1.2d

458

459

459−Draw out a binary tree diagram for each of the following nouns. Try to do this without using the dojo to simplify the expressions.

460+Draw out a binary tree diagram for each of the following nouns. Try to do this without using the Dojo to simplify the expressions.

460

461

461```

462```

4621. [[2 3] 4 [5 6 7]]

4631. [[2 3] 4 [5 6 7]]

@@ -508,12 +509,15 @@ Write the following binary tree as a noun.

508

509

509### 1.2d

510### 1.2d

510

511

511−1. Dojo simplifies the expression

512+1. Dojo simplifies the expression ...

513+

512```

514```

513> [[2 3] 4 [5 6 7]]

515> [[2 3] 4 [5 6 7]]

514[[2 3] 4 5 6 7]

516[[2 3] 4 5 6 7]

515```

517```

518+

516−which has the following tree:

519+... which has the following tree:

520+

517```

521```

518 .

522 .

519 / \

523 / \

@@ -527,13 +531,15 @@ which has the following tree:

527 6 7

531 6 7

528```

532```

529

533

530−2. Dojo simplifies the expression

534+2. Dojo simplifies the expression ...

531

535

532```

536```

533> [[[5 6 7] 8 9] 10 11 [12 13]]

537> [[[5 6 7] 8 9] 10 11 [12 13]]

534[[[5 6 7] 8 9] 10 11 12 13]

538[[[5 6 7] 8 9] 10 11 12 13]

535```

539```

540+

536−which has the following tree:

541+... which has the following tree:

542+

537```

543```

538 .

544 .

539 /\

545 /\

@@ -551,6 +557,7 @@ which has the following tree:

551```

557```

552

558

553### 1.2e

559### 1.2e

560+

554```

561```

555[[[1 2] 3] 4 [5 6] 7]

562[[[1 2] 3] 4 [5 6] 7]

556−```

563+```

tutorials/hoon/recursion.md+7−7

@@ -8,7 +8,7 @@ aliases = ["/docs/learn/hoon/hoon-tutorial/recursion/"]

8[Recursion](.) is a common pattern for solving certain problems in most programming

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

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

11−integers less than or equal to N. Thus the factorial of 5, denoted as _5!_,

11+integers less than or equal to _n_. Thus the factorial of 5, denoted as _5!_,

12would be:

14```

@@ -41,7 +41,7 @@ by the recursion of `n` minus `1`. `$` initiates recursion: it calls the [gate](

41that we're already in, but replaces its sample.

43In our example, we multiply `n` with the product of this _entire gate

44−all over again_ with `$(n (dec n))`, except when that new gate has its sample

44+all over again_ with `$(n (dec n))`, except when that new gate has its sample

45decremented by one. This works recursively because each new gate will, of

46course, itself contain the code to call a further-decremented gate. Gates will

47continue to call new, further-decremented gates until `n` is `1`, and that `1`

@@ -80,7 +80,7 @@ into the `mul` functions behind them.

81#### Tail-Call Optimization

83−Our last example isn't a very efficient use computing resources. The

83+Our last example isn't a very efficient use of computing resources. The

84pyramid-shaped illustration approximates what's happening on the **call stack**, a

85memory structure that tracks the instructions of the program. In our example

86code, every time a parent gate calls another gate, the gate being called is

@@ -111,7 +111,7 @@ function every time.

111To reiterate: if you have to manipulate the result of a recursion as the last

112expression of your gate, as we did in our example, the function is not

113tail-recursive, and therefore not very efficient with memory. A problem arises

114−when we try to recurse more times that we have space on the stack. This will

114+when we try to recurse more times than we have space on the stack. This will

115result in our computation failing and producing a stack overflow. If we tried

116to find the factorial of `5.000.000`, for example, we would almost certainly

117run out of stack space.

@@ -141,8 +141,8 @@ takes one argument `n`. This time, however, we are also putting a face on a

141gate with one [arm](/docs/glossary/arm/) `$` and immediately call it. Think of `|-` as the recursion

142point.

143

144−We then evaluate `n` to see if it is 1. If it is we return the value of `t`. In

144+We then evaluate `n` to see if it is 1. If it is, we return the value of `t`.

145−the case that `n` is anything other than 1, we perform our recursion:

145+In case that `n` is anything other than 1, we perform our recursion:

146

147```hoon

148$(n (dec n), t (mul t n))

@@ -153,7 +153,7 @@ and `t`. `t` is used as an accumulator variable that we use to keep a running

153total for the factorial computation.

154

155Let's use pseudo-Hoon to illustrate how the stack is working in this example for

156−factorial 5.

156+the factorial of 5.

157

158```

159(factorial 5)

tutorials/hoon/setup.md+9−11

@@ -9,20 +9,19 @@ Before we begin working on Hoon, you should first (1) have Urbit installed and (

10## What is an urbit?

12−An **urbit** is an Urbit virtual computer with persistent state that can connect to the Urbit network. (Note the lowercase 'u' here. 'Urbit' is the entire software stack, whereas 'an urbit' is a local instance.) Each urbit is associated with a unique number that plays three distinct roles: (1) it's an address on the Urbit network, (2) it's a cryptographic identity, and (3) it's (in principle) a human memorable name. Normally an urbit's name is represented as a string starting with `~`, as in `~zod` or `~taglux-nidsep`.

12+An **urbit** is an Urbit virtual computer with persistent state that can connect to the Urbit network. (Note the lowercase `u` here. "Urbit" is the entire software stack, whereas "an urbit" is a local instance.) Each urbit is associated with a unique number that plays three distinct roles: (1) it's an address on the Urbit network, (2) it's a cryptographic identity, and (3) it's (in principle) a human memorable name. Normally an urbit's name is represented as a string starting with `~`, as in `~zod` or `~taglux-nidsep`.

14−These may not look like numbers, but they are. Each urbit name is written in a base-256 format, where each 'digit' is a syllable. Imagine your phone number as a pronounceable string which sounds like a name in a foreign language. An ordinary user-level urbit is a 'planet', and it's named by a 32-bit number. The latter is represented as a four-syllable string; e.g., the planet name `~taglux-nidsep` is the number 6,095,360.

14+These may not look like numbers, but they are. Each urbit name is written in a base-256 format, where each "digit" is a syllable. Imagine your phone number as a pronounceable string which sounds like a name in a foreign language. An ordinary user-level urbit is a "planet", and it's named by a 32-bit number. The latter is represented as a four-syllable string; e.g., the planet name `~taglux-nidsep` is the number 6,095,360.

16## Installing Urbit

18−You can install Urbit on any Mac or Unix machine; if you're just trying out Urbit or creating a development ship, you can follow the steps for creating a development ship [here](@/using/develop.md#creating-a-development-ship). On Windows, make a virtual Linux machine using VirtualBox or a similar tool.

18+You can install Urbit on any Mac or Unix machine; if you're just trying out Urbit or creating a development ship, you can follow the steps for creating a development ship [here](@/using/develop.md#creating-a-development-ship). On Windows, make a virtual Linux machine using VirtualBox or a similar tool.

19−

21Once you're finished, you can [boot your very own ship](@/using/install.md#booting-your-ship). While you can develop in Hoon on your own ship on the live network, we strongly suggest developing on a development ship first.

20Once you're finished, you can [boot your very own ship](@/using/install.md#booting-your-ship). While you can develop in Hoon on your own ship on the live network, we strongly suggest developing on a development ship first.

23## Getting started

22## Getting started

25−Once you've created your development ship, let's try a basic command. Type `(add 2 2)` at the prompt and hit return. Your screen now shows:

24+Once you've created your development ship, let's try a basic command. Type `(add 2 2)` at the prompt and hit return. Your screen now shows:

27```

26```

28fake: ~zod

27fake: ~zod

@@ -34,7 +33,7 @@ http: live (insecure, loopback) on 12321

34~zod:dojo>

33~zod:dojo>

35```

34```

37−You just used a function from the Hoon standard library, `add`. Next, quit Urbit with `ctrl-d`:

36+You just used a function from the Hoon standard library, `add`. Next, quit Urbit with `ctrl-d`:

39```

38```

40> (add 2 2)

39> (add 2 2)

@@ -51,9 +50,9 @@ urbit zod

52## Another Noun

51## Another Noun

54−You've already used a standard library function to produce one value, in the dojo. Now that your ship is running again, let's try another. Enter the number `17`.

53+You've already used a standard library function to produce one value, in the Dojo. Now that your ship is running again, let's try another. Enter the number `17`.

56−> We won't show the `~zod:dojo> ` prompt from here on out. We'll just show the echoed command along with its result.

55+> We won't show the `~zod:dojo> ` prompt from here on out. We'll just show the echoed command along with its result.

58You'll see:

57You'll see:

@@ -62,13 +61,13 @@ You'll see:

6217

6117

63```

62```

65−You asked dojo to evaluate `17` and it echoed the number back at you. This value is a 'noun'. We'll talk more about [nouns](/docs/glossary/noun/) in [Lesson 1.2](@/docs/tutorials/hoon/nouns.md), but first let's write a very basic program.

64+You asked Dojo to evaluate `17` and it echoed the number back at you. This value is a "noun". We'll talk more about [nouns](/docs/glossary/noun/) in [Lesson 1.2](@/docs/tutorials/hoon/nouns.md), but first let's write a very basic program.

67## Generators

66## Generators

69Generators are the most straightforward way to write Hoon programs. They are a concept in Arvo, and involve saving Hoon code in a `.hoon` text file. While they aren't strictly part of the Hoon language, we'll be dealing with generators throughout this tutorial.

68Generators are the most straightforward way to write Hoon programs. They are a concept in Arvo, and involve saving Hoon code in a `.hoon` text file. While they aren't strictly part of the Hoon language, we'll be dealing with generators throughout this tutorial.

71−The simplest type of generator is the **naked generator**. All naked generators are `gates`: functions that take an argument and produce an output. Before creating generator you need to mount your `desk` to Unix, for So, to create a generator, all you need to do is write a `gate` and put it into a file in the `/home/gen` directory of your ship as a `.hoon` file. (Assuming you've already mounted with `|mount /=home=`.) After this, you need to run `|commit %home` in dojo and the new file will be recognized by your ship. To run a generator named `mygen.hoon`, you would type `+mygen <argument>` in your ship's Dojo.

70+The simplest type of generator is the **naked generator**. All naked generators are `gates`: functions that take an argument and produce an output. Before creating a generator you need to [mount](https://urbit.org/using/install/#the-dojo) your `desk` to Unix. To create a generator, all you need to do is write a `gate` and put it into a file in the `/home/gen/` directory of your ship as a `.hoon` file. (Assuming you've already mounted with `|mount /=home=`.) After this, you need to run `|commit %home` in Dojo and the new file will be recognized by your ship. To run a generator named `mygen.hoon`, you would type `+mygen <argument>` in your ship's Dojo.

73If this doesn't make sense yet, that's okay. In the [next lesson](@/docs/tutorials/hoon/list-of-numbers.md), we will walk you through an example `gate` that is run as a generator.

72If this doesn't make sense yet, that's okay. In the [next lesson](@/docs/tutorials/hoon/list-of-numbers.md), we will walk you through an example `gate` that is run as a generator.

@@ -104,4 +103,3 @@ Emacs is free and open-source and runs on all major operating systems. It is ava

104#### Vim

103#### Vim

105

104

106Vim is free and open-source and runs on all major operating systems. It is available [here](https://www.vim.org/). Hoon support is available with [hoon.vim](https://github.com/urbit/hoon.vim) and is maintained by Tlon.

105Vim is free and open-source and runs on all major operating systems. It is available [here](https://www.vim.org/). Hoon support is available with [hoon.vim](https://github.com/urbit/hoon.vim) and is maintained by Tlon.

107−

tutorials/hoon/style.md+76−75

@@ -4,25 +4,26 @@ weight = 100

4template = "doc.html"

5aliases = ["docs/learn/hoon/style/"]

6+++

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

8+Welcome to the Hoon style guide. It’s important to familiarize yourself with our way of writing Hoon code.

9## Layout

10## Layout

11−Hoon's position on layout is: so long as your code is (a) correctly commented,

12+Hoon’s position on layout is: so long as your code is (a) correctly commented,

12−(b) free from blank or overlong lines, (c) parses, and (d) looks good, it's good

13+(b) free from blank or overlong lines, (c) parses, and (d) looks good, it’s good

13layout.

14layout.

15When a layout standard or other fundamental coding convention is

16When a layout standard or other fundamental coding convention is

16not perfectly rigid, code can develop some individual flavor.

17not perfectly rigid, code can develop some individual flavor.

17−But Hoon's layout rules, though not rigid, are still strict. The

18+But Hoon’s layout rules, though not rigid, are still strict. The

18flavor should never overwhelm the content.

19flavor should never overwhelm the content.

20### General outline of Hoon syntax

21### General outline of Hoon syntax

22−There are two forms of syntax in Hoon: wide and tall. Wide forms

23+There are two forms of syntax in Hoon: wide and tall. Wide forms

23fit on a single line, use single spaces to separate syntax, and

24fit on a single line, use single spaces to separate syntax, and

24generally use enclosing terminators (like parentheses to close an

25generally use enclosing terminators (like parentheses to close an

25−expression). Tall forms can use multiple lines, separate syntax

26+expression). Tall forms can use multiple lines, separate syntax

26with two spaces at minimum and arbitrary whitespace at maximum,

27with two spaces at minimum and arbitrary whitespace at maximum,

27and avoid terminators when the content has a fixed structure.

28and avoid terminators when the content has a fixed structure.

@@ -41,37 +42,37 @@ or

41```

42```

43These are regular forms -- every rune can be written this way.

44These are regular forms -- every rune can be written this way.

44−Hoon also has a variety of wide [irregular forms](@/docs/reference/hoon-expressions/irregular.md). All tall

45+Hoon also has a variety of wide [irregular forms](@/docs/reference/hoon-expressions/irregular.md). All tall

45−forms are regular. All code within a wide form is wide.

46+forms are regular. All code within a wide form is wide.

46Almost all code has both wide and tall forms, the exception

47Almost all code has both wide and tall forms, the exception

47being named [cores](/docs/glossary/core/).

48being named [cores](/docs/glossary/core/).

49The goal of wide/tall forms is to resemble the look of

50The goal of wide/tall forms is to resemble the look of

50procedural code, with its statement/expression distinction,

51procedural code, with its statement/expression distinction,

51−in a purely functional language. In particular, complex code in

52+in a purely functional language. In particular, complex code in

52functional languages tends to develop a diagonal shape, since

53functional languages tends to develop a diagonal shape, since

53child nodes in the syntax tree are indented right.

54child nodes in the syntax tree are indented right.

55### Tall layout conventions

56### Tall layout conventions

57In wide form, the parser allows no freedom of layout (and no

58In wide form, the parser allows no freedom of layout (and no

58−comments, either). In tall form, there is too much freedom, and so we need

59+comments, either). In tall form, there is too much freedom, and so we need

59−conventions. These conventions aren't absolute, but

60+conventions. These conventions aren’t absolute, but

60−you shouldn't defy them unless you have a good reason to do so.

61+you shouldn’t defy them unless you have a good reason to do so.

62Syntactically, there are three kinds of runes: fixed sequences,

63Syntactically, there are three kinds of runes: fixed sequences,

63−variable sequences, and cores/engines. Let's talk about each.

64+variable sequences, and cores/engines. Let’s talk about each.

65#### Fixed sequences and backstep indentation

66#### Fixed sequences and backstep indentation

67−A fixed sequence is a rune with a fixed number of children. Most

68+A fixed sequence is a rune with a fixed number of children. Most

68−runes are fixed sequences. In wide mode we terminate a fixed

69+runes are fixed sequences. In wide mode we terminate a fixed

69−sequence with a right-parenthesis (rit). In tall mode there is

70+sequence with a right-parenthesis (“rit”). In tall mode there is

70no terminator.

71no terminator.

72−With a fixed sequence, we typically use "backstep indentation."

73+With a fixed sequence, we typically use “backstep indentation.”

73The goal of a backstep is for the largest child node of the rune

74The goal of a backstep is for the largest child node of the rune

74−to end up on the same left margin as the rune itself. This

75+to end up on the same left margin as the rune itself. This

75design ensures that the body of the code flows down the page, not

76design ensures that the body of the code flows down the page, not

76across the page.

77across the page.

@@ -107,13 +108,13 @@ With four (the maximum rune fanout):

107```

108```

108

109

109It is sometimes acceptable to not backstep -- especially in tuple

110It is sometimes acceptable to not backstep -- especially in tuple

110−runes: `:-,` `:_`, `:+` and `+^`. But you should have a specific reason:

111+runes: `:-,` `:_`, `:+` and `+^`. But you should have a specific reason:

111for example: emphasizing symmetry in a tuple.

112for example: emphasizing symmetry in a tuple.

112

113

113#### Variable sequences

114#### Variable sequences

114

115

115Variable sequences can have an arbitrary number of elements, so

116Variable sequences can have an arbitrary number of elements, so

116−they can't self-terminate. They are terminated by a `==` marker.

117+they can’t self-terminate. They are terminated by a `==` marker.

117The sequence, or its variable part, is indented and vertical:

118The sequence, or its variable part, is indented and vertical:

118

119

119```hoon

120```hoon

@@ -123,7 +124,7 @@ The sequence, or its variable part, is indented and vertical:

123 ==

124 ==

124```

125```

125

126

126−Another representation wastes a line, but saves an indent. Use

127+Another representation wastes a line, but saves an indent. Use

127this only for very long sequences:

128this only for very long sequences:

128

129

129```hoon

130```hoon

@@ -135,8 +136,8 @@ this only for very long sequences:

135```

136```

136

137

137Some variable sequences are sequences of pairs; some of these

138Some variable sequences are sequences of pairs; some of these

138−start with fixed sequences of nodes. Pair sequences are in

139+start with fixed sequences of nodes. Pair sequences are in

139−either "kingside" or "queenside" convention, depending on what

140+either “kingside” or “queenside” convention, depending on what

140looks better for this particular code.

141looks better for this particular code.

141

142

142Kingside format:

143Kingside format:

@@ -172,7 +173,7 @@ It is also usually hard to read without linebreak comments,

172as demonstrated above.

173as demonstrated above.

173

174

174We sometimes end up with multiple terminators on separate lines,

175We sometimes end up with multiple terminators on separate lines,

175−two or more spaces apart. These lines can be collapsed:

176+two or more spaces apart. These lines can be collapsed:

176

177

177```hoon

178```hoon

178 ?+ x default

179 ?+ x default

@@ -191,10 +192,10 @@ Modern Hoon naming is **verbose**.

191**Never**: abbreviate a label; pack characters (try to reduce the

192**Never**: abbreviate a label; pack characters (try to reduce the

192length of labels, or make lengths match up between parallel

193length of labels, or make lengths match up between parallel

193labels); use intentionally vague and meaningless words; or use

194labels); use intentionally vague and meaningless words; or use

194−nonsense text that isn't a word.

195+nonsense text that isn’t a word.

195

196

196−It can't be repeated too often: **do not abbreviate words, unless

197+It can’t be repeated too often: **do not abbreviate words, unless

197−you would use the same abbreviations in written English**. To

198+you would use the same abbreviations in written English**. To

198save a trivial, one-time amount of work in typing, you are adding

199save a trivial, one-time amount of work in typing, you are adding

199a nontrivial amount of work and ambiguity in reading.

200a nontrivial amount of work and ambiguity in reading.

200

201

@@ -206,16 +207,16 @@ Hoon comments are 8-column lines which contain whitespace, then

206Blank lines are lines containing no characters, or only whitespace.

207Blank lines are lines containing no characters, or only whitespace.

207There must never be blank lines in a Hoon file.

208There must never be blank lines in a Hoon file.

208

209

209−Empty lines are lines containing `::` only. There must never be

210+Empty lines are lines containing `::` only. There must never be

210two empty lines in a row in a Hoon file.

211two empty lines in a row in a Hoon file.

211

212

212−Whitespace is semi-significant. The difference between a

213+Whitespace is semi-significant. The difference between a

213−space and a gap (more than one space) is significant. But two or

214+space and a gap (more than one space) is significant. But two or

214more spaces, newlines, or comments are one gap.

215more spaces, newlines, or comments are one gap.

215

216

216#### Comment conventions

217#### Comment conventions

217

218

218−Hoon suggests "breathing comments." There should always be an

219+Hoon suggests “breathing comments.” There should always be an

219empty comment line between a comment and the line **below** it:

220empty comment line between a comment and the line **below** it:

220

221

221```hoon

222```hoon

@@ -227,7 +228,7 @@ empty comment line between a comment and the line **below** it:

227 this.is.more.code

228 this.is.more.code

228```

229```

229

230

230−Sometimes dense code does need air on both sides. Also

231+Sometimes dense code does need air on both sides. Also

231legitimate:

232legitimate:

232

233

233```hoon

234```hoon

@@ -243,16 +244,16 @@ legitimate:

243But air on both sides is needed less often than you may think.

244But air on both sides is needed less often than you may think.

244

245

245Crowded comments are comments on lines which also contain code.

246Crowded comments are comments on lines which also contain code.

246−Older code has a lot of these, especially the "column 56"

247+Older code has a lot of these, especially the “column 56”

247standard.

248standard.

248

249

249−Crowded comments are considered harmful -- don't use them. Hoon,

250+Crowded comments are considered harmful -- don’t use them. Hoon,

250like any higher-order functional language, can be very dense and

251like any higher-order functional language, can be very dense and

251−powerful. We almost never want it to be **more** dense.

252+powerful. We almost never want it to be **more** dense.

252

253

253#### Megalithic comments

254#### Megalithic comments

254

255

255−In older code you'll also see attempts to produce large, visually

256+In older code you’ll also see attempts to produce large, visually

256salient geometries as separators, like:

257salient geometries as separators, like:

257

258

258```

259```

@@ -267,8 +268,8 @@ or

267 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

268 ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

268```

269```

269

270

270−Please don't do this in new code. Normal conventions should be

271+Please don’t do this in new code. Normal conventions should be

271−legible. Use more deeply qualified positions if your code is

272+legible. Use more deeply qualified positions if your code is

272hard to navigate.

273hard to navigate.

273

274

274### Structure of all comments, formal and informal

275### Structure of all comments, formal and informal

@@ -285,10 +286,10 @@ development process).

285All kinds of formal comments have the same structure: simple or

286All kinds of formal comments have the same structure: simple or

286complex.

287complex.

287

288

288−A simple formal comment is a one-line headline. A headline is

289+A simple formal comment is a one-line headline. A headline is

289optional whitespace; then `::`; then two spaces; then a parsed

290optional whitespace; then `::`; then two spaces; then a parsed

290line of **lowercase** ASCII whose syntax depends on the comment

291line of **lowercase** ASCII whose syntax depends on the comment

291−type. Like this:

292+type. Like this:

292

293

293```hoon

294```hoon

294 :: $foo: the definition of a foo

295 :: $foo: the definition of a foo

@@ -301,23 +302,23 @@ four spaces, in ASCII mixed case:

301```hoon

302```hoon

302 :: $foo: the definition of a foo

303 :: $foo: the definition of a foo

303 ::

304 ::

304− :: The source of the word "foo" is lost in history. Some

305+ :: The source of the word “foo” is lost in history. Some

305− :: think it comes from the WWII military term "FUBAR,"

306+ :: think it comes from the WWII military term “FUBAR,”

306− :: in which "UBAR" stands for "up beyond all retrieval."

307+ :: in which “UBAR” stands for “up beyond all retrieval.”

307 ::

308 ::

308− :: Somehow "FUBAR" became "foobar." The rest is history.

309+ :: Somehow “FUBAR” became “foobar.” The rest is history.

309 ::

310 ::

310```

311```

311

312

312The point is: sometimes we want to see a deep explanation;

313The point is: sometimes we want to see a deep explanation;

313−sometimes we just want a summary. So we require you to either

314+sometimes we just want a summary. So we require you to either

314(a) provide a line-length explanation, or (b) a long screed

315(a) provide a line-length explanation, or (b) a long screed

315but with a line-length summary/headline.

316but with a line-length summary/headline.

316

317

317### Feature comments

318### Feature comments

318

319

319A feature headline is `::`, then two spaces, then a qualified

320A feature headline is `::`, then two spaces, then a qualified

320−location, then `:`, then a freeform string. Like:

321+location, then `:`, then a freeform string. Like:

321

322

322```hoon

323```hoon

323 :: $foo: a the definition of a foo

324 :: $foo: a the definition of a foo

@@ -326,8 +327,8 @@ location, then `:`, then a freeform string. Like:

326```

327```

327

328

328We find the feature `$foo` relative to the current location and

329We find the feature `$foo` relative to the current location and

329−move the comment there, as described above. In most cases it

330+move the comment there, as described above. In most cases it

330−becomes a product comment. For a `|chapter` (which does not

331+becomes a product comment. For a `|chapter` (which does not

331resolve to any data value) it becomes the chapter description.

332resolve to any data value) it becomes the chapter description.

332

333

333### Product comments

334### Product comments

@@ -348,22 +349,22 @@ Flow comments use a new commenting concept called **legends**.

348#### Legends

349#### Legends

349

350

350One of the problems with Hoon as a language is that it takes some

351One of the problems with Hoon as a language is that it takes some

351−time to learn to look at a tree of runes and "see the function."

352+time to learn to look at a tree of runes and “see the function.”

352−Seeing the function is beautiful and pleasant. But until the new

353+Seeing the function is beautiful and pleasant. But until the new

353Hoon student has put in a lot of practice, this experience is

354Hoon student has put in a lot of practice, this experience is

354−inaccessible. And tracing runes with a manual is hard.

355+inaccessible. And tracing runes with a manual is hard.

355

356

356Canonical flow comments are one way to ease this burden.

357Canonical flow comments are one way to ease this burden.

357−them, we first need to write descriptive names (not necessarily

358+We first need to write descriptive names (not necessarily

358−unique) for every leg of every rune case. Then, we introduce a

359+unique) for every leg of every rune case. Then, we introduce a

359narration of the code with these descriptions.

360narration of the code with these descriptions.

360

361

361−For example, let's fix `[%wtcl p=hoon q=hoon r=hoon]`. Let's

362+For example, let’s fix `[%wtcl p=hoon q=hoon r=hoon]`. Let’s

362−make it... `[%wtcl if=hoon then=hoon else=hoon]`. Then we

363+make it … `[%wtcl if=hoon then=hoon else=hoon]`. Then we

363could write flow comments as follows:

364could write flow comments as follows:

364

365

365```hoon

366```hoon

366− ?: :: if, it's it winter

367+ ?: :: if, it is winter

367 ::

368 ::

368 is-winter

369 is-winter

369 :: then, why not rome?

370 :: then, why not rome?

@@ -377,12 +378,12 @@ could write flow comments as follows:

377The headline of a flow comment uses a **legend**: the name of

378The headline of a flow comment uses a **legend**: the name of

378this leg in the parent rune, then a message,

379this leg in the parent rune, then a message,

379

380

380−For someone who doesn't know Hoon, these pseudo-keywords are

381+For someone who doesn’t know Hoon, these pseudo-keywords are

381−a lifesaver. For someone who does, they are not too annoying

382+a lifesaver. For someone who does, they are not too annoying

382and may still be helpful.

383and may still be helpful.

383

384

384−Of course, to use this we need to write useful "leg ends" for all

385+Of course, to use this we need to write useful “leg ends” for all

385−appropriate legs of all appropriate runes. But that will

386+appropriate legs of all appropriate runes. But that will

386probably help us document them, anyway.

387probably help us document them, anyway.

387

388

388#### Flow promotion

389#### Flow promotion

@@ -391,7 +392,7 @@ Sometimes, just for cosmetic reasons, we like to raise the

391comment on the first leg of a rune up above the parent:

392comment on the first leg of a rune up above the parent:

392

393

393```hoon

394```hoon

394− :: if, it's it winter

395+ :: if, it is winter

395 ::

396 ::

396 ?: is-winter

397 ?: is-winter

397 :: then, why not rome?

398 :: then, why not rome?

@@ -402,10 +403,10 @@ comment on the first leg of a rune up above the parent:

402 visit-holland

403 visit-holland

403```

404```

404

405

405−This can make flow comments collide, as in "else, if," below:

406+This can make flow comments collide, as in “else, if,” below:

406

407

407```hoon

408```hoon

408− :: if, it's winter

409+ :: if, it is winter

409 ::

410 ::

410 ?: is-winter

411 ?: is-winter

411 :: then, why not rome?

412 :: then, why not rome?

@@ -426,7 +427,7 @@ This can make flow comments collide, as in "else, if," below:

426

427

427Flow comments, because they describe what your code is doing, are

428Flow comments, because they describe what your code is doing, are

428embedded in the stack trace, using the same hint mechanism as

429embedded in the stack trace, using the same hint mechanism as

429−`~|`. A trace is an explanation of everything your code was

430+`~|`. A trace is an explanation of everything your code was

430doing when it crashed.

431doing when it crashed.

431

432

432And data interpolation, in `{}`, also works in flow comments.

433And data interpolation, in `{}`, also works in flow comments.

@@ -435,7 +436,7 @@ English, including data.

435

436

436## Grading

437## Grading

437

438

438−How do we define the superficial quality of Hoon code? (Setting

439+How do we define the superficial quality of Hoon code? (Setting

439aside, of course, the question of whether the code is computing

440aside, of course, the question of whether the code is computing

440the right thing in the right way.)

441the right thing in the right way.)

441

442

@@ -446,30 +447,30 @@ Any file that looks like code and opens in an editor gets an F.

446If it compiles, and it is Hoon, it gets a D.

447If it compiles, and it is Hoon, it gets a D.

447

448

448A Hoon file that follows the layout, structure, and naming

449A Hoon file that follows the layout, structure, and naming

449−conventions in this document has earned a C. Weird indents,

450+conventions in this document has earned a C. Weird indents,

450cryptic or abbreviated names, etc, etc, preclude an A or B

451cryptic or abbreviated names, etc, etc, preclude an A or B

451grade -- regardless of documentation.

452grade -- regardless of documentation.

452

453

453A Hoon file gets a B if and only if **every symbol in the file is

454A Hoon file gets a B if and only if **every symbol in the file is

454−defined, where introduced, by a formal comment**. You do not get

455+defined, where introduced, by a formal comment**. You do not get

455to make up a name without writing a one-line definition.

456to make up a name without writing a one-line definition.

456

457

457For an A, there are two criteria.

458For an A, there are two criteria.

458

459

459One: every symbol that needs an explanation (a multiline comment

460One: every symbol that needs an explanation (a multiline comment

460−after the definition) has an explanation. This is obviously a

461+after the definition) has an explanation. This is obviously a

461−judgment call, as a grade of A should always be. If a definition

462+judgment call, as a grade of A should always be. If a definition

462−doesn't call for any explanation, it must be dead obvious.

463+doesn’t call for any explanation, it must be dead obvious.

463

464

464Two: every `%constant` we use must be defined where it is used,

465Two: every `%constant` we use must be defined where it is used,

465−not just where it's declared.

466+not just where it’s declared.

466

467

467The advantage of a `%constant` over a classic `typedef`: there is no

468The advantage of a `%constant` over a classic `typedef`: there is no

468−need to search formally for a symbol. The disadvantage: there is

469+need to search formally for a symbol. The disadvantage: there is

469−no trivial way to find out what the symbol actually means. So

470+no trivial way to find out what the symbol actually means. So

470when I send some `%foobar` move, I should define what I think

471when I send some `%foobar` move, I should define what I think

471−`%foobar` means. Just copy and paste the original definition.

472+`%foobar` means. Just copy and paste the original definition.

472

473

473−Code shouldn't even try for an A until it is quite stable. The worst

474+Code shouldn’t even try for an A until it is quite stable. The worst

474thing in the world is code that changes without updating the documentation.

475thing in the world is code that changes without updating the documentation.

475Any **incorrect** comment in a file drops it all the way back to a D.

476Any **incorrect** comment in a file drops it all the way back to a D.

tutorials/sail-and-udon.md+100−100

@@ -5,9 +5,9 @@ template = "doc.html"

5aliases = ["docs/using/sail-and-udon/"]

6+++

8−Sail is Hoon markup that’s used to render a web page with XML. But what makes it special is that you can run arbitrary Hoon code within such a web page without using a separate markup language.

8+Sail is Hoon markup that's used to render a web page with XML. But what makes it special is that you can run arbitrary Hoon code within such a web page without using a separate markup language.

10−Udon is a way to write content for the web. It’s a minimalist markup language for creating and rendering text documents, with a Markdown-inspired syntax. It’s integrated with our Hoon programming language, allowing it to be used as standalone prose in its own file or embedded inside a Hoon source file, in which case it will be parsed into a tree of HTML nodes using Sail.

10+Udon is a way to write content for the web. It's a minimalist markup language for creating and rendering text documents, with a Markdown-inspired syntax. It's integrated with our Hoon programming language, allowing it to be used as standalone prose in its own file or embedded inside a Hoon source file, in which case it will be parsed into a tree of HTML nodes using Sail.

12This document will be divided into two main sections: the Sail guide and the Udon guide. Also, you should read the Getting Started section below, which applies to both Udon and Sail.

@@ -25,9 +25,9 @@ Before starting with either Sail or Udon, make sure that your ship is

25[mounted to Unix](@/using/install.md).

27To host that output, your ship also has a web-server that can be found at

28−`http://localhost/` (default port 80) if it’s your first ship that’s running on the

28+`http://localhost/` (default port 80) if it's your first ship that's running on the

29−machine, `http://localhost:8081/` if it’s the second ship on that same machine,

29+machine, `http://localhost:8081/` if it's the second ship on that same machine,

30−and so on. In the startup messages, a ship will tell you which HTTP port it’s

30+and so on. In the startup messages, a ship will tell you which HTTP port it's

31using.

33Udon and Sail files are often run as independent files (`.udon` and `.hoon`

@@ -35,7 +35,7 @@ respectively), but for the purpose of this guide, we will run them out of the

35`frontpage.hoon` file located in the `/gen` directory. The default content of

36`frontpage.hoon` is Sail code.

38−To use `frontpage.hoon`, we use a `|serve` command like this one in your ship’s

38+To use `frontpage.hoon`, we use a `|serve` command like this one in your ship's

39Dojo:

41```

@@ -54,13 +54,13 @@ Run the command `|serve /test %home /gen/frontpage/hoon`. Now navigate to

54`http://localhost/test` (or `http://localhost:8081/test` if your ship is on that port) in your

55browser, and you should see the rendered Sail.

57−**Note:** Important to remember that every time you edit a file in your ship’s

57+**Note:** Important to remember that every time you edit a file in your ship's

58pier (Unix directory), including `frontpage.hoon`, you need to run `|commit %home`

59to copy those changes to Urbit.

61## <a name="sail"></a>Sail: A Guide

63−It’s easy to see how Sail can directly translate to HTML:

63+It's easy to see how Sail can directly translate to HTML:

65### Sail code

@@ -72,7 +72,7 @@ It’s easy to see how Sail can directly translate to HTML:

72 ;body

73 ;h1: Welcome!

74 ; Hello, world!

75− ; We’re on the web.

75+ ; We're on the web.

76 ;div;

77 ;script@"http://unsafely.tracking.you/cookiemonster.js";

78 ==

@@ -89,7 +89,7 @@ It’s easy to see how Sail can directly translate to HTML:

89 <body>

90 <h1>Welcome!</h1>

91 Hello, world!

92− We’re on the web.

92+ We're on the web.

93 <div></div>

94 <script src="http://unsafely.tracking.you/cookiemonster.js"></script>

95 </body>

@@ -98,17 +98,17 @@ It’s easy to see how Sail can directly translate to HTML:

99You can test above Sail code by placing it

100under `^- manx` in your `frontpage.hoon` file, and then running `|commit %home`

101−in the Dojo. If you’ve already run the `|serve` command code from the first

101+in the Dojo. If you've already run the `|serve` command code from the first

102section, the new content should appear at `http://localhost/test`.

103

104−It shouldn’t be hard to see the similarities between Sail and HTML. So let’s go

104+It shouldn't be hard to see the similarities between Sail and HTML. So let's go

105into more detail about what the differences are.

106

107### Tags and Closing

108

109In Sail, tag heads are written with the tag name prepended by `;`. Unlike in

110HTML, there are different ways on closing tags, depending on the needs of the

111−tag. One of the nice things about Hoon is that you don’t have to be constantly

111+tag. One of the nice things about Hoon is that you don't have to be constantly

112closing expressions; Sail inherits this convenience.

113

114#### Empty

@@ -172,7 +172,7 @@ those untagged lines with `;`.

172;body

173 ;h1: Welcome!

174 ; Hello, world!

175− ; We’re on the web.

175+ ; We're on the web.

176==

177```

178

@@ -182,7 +182,7 @@ Equals:

182<body>

183 <h1>Welcome!</h1>

184 Hello, world!

185− We’re on the web.

185+ We're on the web.

186</body>

187```

188

@@ -194,15 +194,15 @@ Adding attributes is simple: just add the desired attribute between parentheses,

194right after the tag name without a space. We separate different attributes of

195the same node by using `,`.

196

197−Attributes can be used in two forms: flat, which uses one line; and tall, which

197+Attributes can be used in two forms: wide, which uses one line; and tall, which

198−uses multiple lines, when a single line would not be practical. Flat forms and

198+uses multiple lines, when a single line would not be practical. Wide forms and

199tall forms are two syntaxes of semantically equivalent expressions.

200

201#### Generic

202

203−The code below produces a “Submit” button on the page.

203+The code below produces a "Submit" button on the page.

204

205−Flat-form Sail:

205+Wide-form Sail:

206

207```

208;input(type "submit", value "Submit");

@@ -299,7 +299,7 @@ with Hoon code.

299One place where Sail diverges from HTML is that it supports string

300interpolation. In Sail, the contents of all tags are a string type called `tape`

301unless otherwise designated. Tapes are delineated by the double quotes `""`.

302−That’s important, because tapes can be interpolated with Hoon expressions,

302+That's important, because tapes can be interpolated with Hoon expressions,

303provided that those expressions produce something a tape as well. Interpolation

304is done by wrapping the code to be inserted in `{}`. In your Dojo prompt, try

305the command below (without the `>`):

@@ -322,7 +322,7 @@ following command in your Dojo:

32233

323```

324

325−This should work, producing `33`, an atom. That’s our problem. The

325+This should work, producing `33`, an atom. That's our problem. The

326interpolation expression expects a tape, but our first command tried to

327interpolate with something that results in an atom. Try this now:

328

@@ -331,8 +331,8 @@ interpolate with something that results in an atom. Try this now:

331"33"

332```

333

334−We get a similar result, but we know that it’s a tape because it’s wrapped in

334+We get a similar result, but we know that it's a tape because it's wrapped in

335−`""`. Bingo! With this knowledge, let’s perform a successful interpolation:

335+`""`. Bingo! With this knowledge, let's perform a successful interpolation:

336

337```

338> "I am a l{<(mul 3 11)>}t Urbit user."

@@ -365,7 +365,7 @@ Then enter the following command in the Dojo:

365> .

366```

367

368−You’ll notice that the Sail subject is like a stripped-down version of the Dojo

368+You'll notice that the Sail subject is like a stripped-down version of the Dojo

369subject. Its final line should match the Dojo subject.

370

371Now swap the code below into your Sail file.

@@ -380,15 +380,15 @@ Now swap the code below into your Sail file.

380==

381```

382

383−You’ll find that the resulting Sail subject is much larger. If you look closely,

383+You'll find that the resulting Sail subject is much larger. If you look closely,

384−you’ll see that there’s some new similarities with the Dojo subject, such as

384+you'll see that there's some new similarities with the Dojo subject, such as

385−containing the name of your ship. There’s also some new differences, since

385+containing the name of your ship. There's also some new differences, since

386`fuel:html` contains things that are specifically useful for performing

387web-related operations.

388

389### A More Interesting Example

390

391−Now let’s apply knowledge of string interpolation and the Sail subject in a Sail

391+Now let's apply knowledge of string interpolation and the Sail subject in a Sail

392source file. The following code produces more interesting things than the

393example we saw before.

394

@@ -414,13 +414,13 @@ example we saw before.

414 ;span: Check it out!

415 ;+ ?: show-list

416 ;ol

417− ;li(style "color: green"): We’re doing interesting stuff now.

417+ ;li(style "color: green"): We're doing interesting stuff now.

418− ;li: We’re pretty-printing this sum with Hoon: {<(add 50 50)>}.

418+ ;li: We're pretty-printing this sum with Hoon: {<(add 50 50)>}.

419 ;li: The code above is shorthand for {(scow %ud (add 50 50))}.

420 ;li: I am {(trip '~lodleb-ritrul')}.

421− ;li: Actually, my name is {<p.bem.gas>}. I’m a {what-kind}.

421+ ;li: Actually, my name is {<p.bem.gas>}. I'm a {what-kind}.

422 ==

423− ;div: My name is {<p.bem.gas>}. I’m a {what-kind}.

423+ ;div: My name is {<p.bem.gas>}. I'm a {what-kind}.

424 ==

425==

426```

@@ -429,7 +429,7 @@ Save the above Sail code in to `home/web/pages/secondsail.hoon` and access the

429resulting page by navigating to `http://localhost:8080/pages/secondsail` in

430your browser.

431

432−There are some interesting things here. Let’s go through this code piece by

432+There are some interesting things here. Let's go through this code piece by

433piece.

434

435```

@@ -443,17 +443,17 @@ against its own subject, `our` is not part of the default subject. To augment

443our subject with the information that we need, we use `/= gas /$ fuel:html`.

444

445The above expression uses two Ford runes, `/=` and `/$`, to add the relevant

446−information to the current subject. We can pull the ship’s name out of this

446+information to the current subject. We can pull the ship's name out of this

447−augmented subject later. It’s important to note that these runes are not part of

447+augmented subject later. It's important to note that these runes are not part of

448Hoon. They are part of Ford, our build system.

449

450`/$` is used to get data from the environment, and `/=` adds that data to

451subject in the face `gas`. The

452[Ford user manual](https://urbit.org/docs/arvo/internals/ford/runes/) has

453−details on these and other Ford runes, but understanding these runes isn’t

453+details on these and other Ford runes, but understanding these runes isn't

454necessary for the purposes of this tutorial.

455

456−`fuel:html` gets extra data from your ship’s Eyre module, which handles all

456+`fuel:html` gets extra data from your ship's Eyre module, which handles all

457things HTTP, and sticks it in the subject when Eyre renders a page. This

458includes the name of the ship, which is what we look for in the next line, but

459it includes much more.

@@ -485,7 +485,7 @@ the source code.

485 "comet"

486```

487

488−This code chunk is a series of conditionals that checks the host ship’s name to

488+This code chunk is a series of conditionals that checks the host ship's name to

489see what its value is.

490

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

@@ -493,7 +493,7 @@ subject and gives it the face `wid`. This noun is produced by the the

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

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

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

496−3 are bitwidths of 8; `2^3 = 8`) are fully contained in your ship’s address.

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

497

498Galaxies contain zero to one 3-blocks; stars contain two 3-blocks; planets

499contain three to four 3-blocks; moons contain five to eight 3-blocks; comets

@@ -554,25 +554,25 @@ In the following lines, we begin to use some Hoon expressions again.

554In the top line in the chunk above, we use the `;+` Sail rune, which

555resolves an expression to a single node. That expression, in this case, is

556`?:`, which tests the truth value of `show-list`, which we assigned the value

557−`&` (meaning `true`) at the beginning of the program. It’s closed by the `==` on

557+`&` (meaning `true`) at the beginning of the program. It's closed by the `==` on

558the last line.

559

560Thus, this program resolves to the first child of `show-list`, the node `;ol`.

561That node creates an ordered list, and the items contained within that node.

562

563```

564− ;li(style "color: green"): We’re doing more interesting stuff now.

564+ ;li(style "color: green"): We're doing more interesting stuff now.

565```

566

567The line above is the only element of this list that does not use

568Hoon proper. The line renders as green, as interpreted by the browser,

569because of the Sail attribute.

570

571−The next items in the list use `{}`. Recall that these braces, pronounced “lob”

571+The next items in the list use `{}`. Recall that these braces, pronounced "lob"

572−and “rob” in Hoon-speak, allow for the interpolation of code within a string.

572+and "rob" in Hoon-speak, allow for the interpolation of code within a string.

573

574```

575− ;li: We’re pretty-printing this sum with Hoon: {<(add 50 50)>}.

575+ ;li: We're pretty-printing this sum with Hoon: {<(add 50 50)>}.

576```

577

578The line above is interpolated with Hoon code that produces the sum of 50 plus

@@ -585,7 +585,7 @@ tape, like the rest of the line.

585

586The `{(scow %ud (add 50 50)}` on this line is just a different way

587writing the `{<(add 50 50)>}` expression. `scow` is a Hoon function that turns a

588−noun into a `tape`, Hoon’s string type. `%ud` tells `scow` that its argument

588+noun into a `tape`, Hoon's string type. `%ud` tells `scow` that its argument

589should be displayed in the form of an unsigned decimal.

590

591```

@@ -599,7 +599,7 @@ tape. So, by converting `~lodleb-ritrul` to a tape, it can be included in the

599tape that we are trying to insert it into without getting a type error.

600

601```

602− ;li: Actually, my name is {<p.bem.gas>}. I’m a {what-kind}.

602+ ;li: Actually, my name is {<p.bem.gas>}. I'm a {what-kind}.

603 ==

604```

605

@@ -613,23 +613,23 @@ within `gas`, which happens to be where the name of the ship is located.

613Note that `{what-kind}` does not have a `<>` wrapper. Why do you think this is?

614

615```

616− ;div; My name is {<p.bem.gas>}. I’m a {ship}.

616+ ;div; My name is {<p.bem.gas>}. I'm a {ship}.

617 ==

618==

619```

620

621The `;div;` node above is only rendered, as an alternative to the above list,

622−if `show-list` is evaluated as `true`. This means it won’t be shown with your

622+if `show-list` is evaluated as `true`. This means it won't be shown with your

623default code. To show this line, change the `&` on line 2 to `|` (`false`).

624

625### Sail Runes

626

627−In the previous example, we used a few special runes that aren’t used in typical

627+In the previous example, we used a few special runes that aren't used in typical

628Hoon code. But there are others that are worth learning about at this point.

629

630`;+` is an expression that resolves to a single node. We saw this on line 20

631in our Sail example above: `;+ ?: show-list` resolves to the node `;ol` and

632−all of that node’s children.

632+all of that node's children.

633

634`;*` is an expression that resolves to a list of nodes. If we want to render

635multiple nodes side-by-side, and not just the children of a single node, this

@@ -637,7 +637,7 @@ is the expression that we use.

637

638`;=` turns a tuple of nodes into a list of nodes.

639

640−To see how these runes work, let’s take a chunk of our previous code starting at

640+To see how these runes work, let's take a chunk of our previous code starting at

641line 20 and modify it a bit:

642

643```

@@ -647,7 +647,7 @@ line 20 and modify it a bit:

647 ;li: Actually, my name is {<p.bem.gas>}.

648 ==

649 ;=

650− ;div: My name is {<p.bem.gas>}. I’m a {what-kind}.

650+ ;div: My name is {<p.bem.gas>}. I'm a {what-kind}.

651 ;div: No list here!

652 ==

653 ==

@@ -659,8 +659,8 @@ side-by-side -- notice that the `;ol` is absent from the first branch.

659We begin with the `;*` rune, which resolves to a list of nodes, instead of the

660`;+` rune, which only resolves to a single node.

661

662−But that’s not enough on its own. `;*` needs to resolve to a list, and a few

662+But that's not enough on its own. `;*` needs to resolve to a list, and a few

663−Sail nodes aren’t lists until they are explicitly made into lists. Until we wrap

663+Sail nodes aren't lists until they are explicitly made into lists. Until we wrap

664those nodes in `;=`, the nodes treated as mere tuples. All branches must be

665valid lists for the `;* ?: show-list` expression to resolve.

666

@@ -676,15 +676,15 @@ learn more about how the renderer works, take a look at the

676

677## Udon: A Guide {#udon}

678

679−Udon is a way to write content for the web. It’s a minimalist

679+Udon is a way to write content for the web. It's a minimalist

680markup language for creating and rendering text documents, with a

681−Markdown-inspired syntax. It’s integrated with our Hoon programming language,

681+Markdown-inspired syntax. It's integrated with our Hoon programming language,

682allowing it to be used as standalone prose in its own file or embedded inside a

683Hoon source file, in which case it will be parsed into a tree of HTML nodes

684−using Hoon’s XML-templating syntax, Sail.

684+using Hoon's XML-templating syntax, Sail.

685

686There are quite a few similarities between Udon and the

687−CommonMark standard, but there are enough differences that you shouldn’t rely on

687+CommonMark standard, but there are enough differences that you shouldn't rely on

688existing knowledge of the latter. Udon generally supports only one

689syntax for each type of HTML node it emits. Udon is also stricter than

690Markdown: some syntax errors will prevent the file from being parsed at all.

@@ -696,7 +696,7 @@ will use the `frontpage.hoon` method that we are already familiar with.

696

697To test out Udon, put a `;>` under the `^- manx` in your `frontpage.hoon` file,

698and then put all your Udon code under that `;>`. Then run `|commit %home`

699−in the Dojo. If you’ve already run the `|serve` command code from the first

699+in the Dojo. If you've already run the `|serve` command code from the first

700section, the new content should appear at `http://localhost/test`.

701

702## Udon Syntax

@@ -710,7 +710,7 @@ The first thing on a `.udon` file is a chunk of code called the front matter. It

710contains metadata about your page, such as date, title, and position relative

711to sibling pages.

712

713−As an example, let’s look at the front matter of this very page:

713+As an example, let's look at the front matter of this very page:

714

715```

716:- :~ navhome/'/docs/'

@@ -720,14 +720,14 @@ As an example, let’s look at the front matter of this very page:

720;>

721```

722

723−What’s going on here?

723+What's going on here?

724

725`:-`, the Hoon rune for creating a cell, creates a cell composed of

726the `:~` Hoon rune for creating a list, and `;>`, which is a Sail rune

727for Udon.

728

729`:~` creates a list out of the three elements: `navhome/'/docs/'`, which

730−indicates that navigating “home” will bring you to the urbit.org/docs section

730+indicates that navigating "home" will bring you to the urbit.org/docs section

731of the website; `sort/'28'`, which assigns it the 28th position of the

732immediate section that contains it, the one you see in the sidebar;

733and `title/'Udon'`, which gives the page its title. The `==` digraph

@@ -735,7 +735,7 @@ terminates the list.

735

736`;>` is a Sail rune that creates a node that contains everything that follows

737it, telling the parser that this text should be interpreted as Udon.

738−It’s not technically front matter, but you’ll always find it following the

738+It's not technically front matter, but you'll always find it following the

739front matter, since all Udon must come after this rune.

740

741The categories listed in the example above -- `navhome`, `sort`, and `title` --

@@ -803,22 +803,22 @@ the _same line_.

803**Example:**

804

805```

806−Here’s the first line.

806+Here's the first line.

807

808−This second line is separated by two newlines, so it’s a separate paragraph.

808+This second line is separated by two newlines, so it's a separate paragraph.

809

810−This line looks like a distinct paragraph, but …

810+This line looks like a distinct paragraph, but ...

811−It’s only separated by a single newline, so it’s included in the same paragraph.

811+It's only separated by a single newline, so it's included in the same paragraph.

812```

813

814**Produces:**

815

816−Here’s the first line.

816+Here's the first line.

817

818−This second line is separated by two newlines, so it’s a separate paragraph.

818+This second line is separated by two newlines, so it's a separate paragraph.

819

820−This line looks like a distinct paragraph, but …

820+This line looks like a distinct paragraph, but ...

821−It’s only separated by a single newline, so it’s included in the same paragraph.

821+It's only separated by a single newline, so it's included in the same paragraph.

822

823#### Backslash Line Break

824

@@ -871,13 +871,13 @@ New list elements are delineated by newlines beginning with list symbols of

871the appropriate type (`-` or `+`).

872

873Just as with non-list text, text on a bare newline will appear on the line before,

874−separated by a space. A `\\` is used to create a line-break that isn’t the list

874+separated by a space. A `\\` is used to create a line-break that isn't the list

875−itself and isn’t a list. Both of these kinds of newlines must be indented by two

875+itself and isn't a list. Both of these kinds of newlines must be indented by two

876spaces, or else the page will not parse.

877

878Indentation is also used for creating nested sub-lists. Sub-lists of one kind

879−can be used with parent lists of the other kind. Sub-lists can’t be nested

879+can be used with parent lists of the other kind. Sub-lists can't be nested

880−directly after either kind of aforementioned newline that isn’t a list element;

880+directly after either kind of aforementioned newline that isn't a list element;

881only lines that are themselves list elements can nest sub-lists.

882

883A newline after a blank line is interpreted as a new paragraph in normal text.

@@ -895,15 +895,15 @@ followed by a `\\` on its own line.

895- Chicken\

896 Make sure that you get enough for the barbecue

897- Bread

898− + Ask the baker what’s fresh

898+ + Ask the baker what's fresh

899 + Buy the second-freshest batch

900- Cereal

901

902\

903+ First, separate eggs into a bowl

904+ Then, add a splash of cream

905− - If you don’t have cream, you can use milk, but cream is preferred

905+ - If you don't have cream, you can use milk, but cream is preferred

906− + If you don’t have milk or cream, melt an eighth of a stick of butter on

906+ + If you don't have milk or cream, melt an eighth of a stick of butter on

907 a skillet

908 + Scramble the eggs in the bowl

909 + Pour the eggs onto the skillet before the butter browns

@@ -925,15 +925,15 @@ Produces

925- Chicken\

926 Make sure that you get enough for the barbecue

927- Bread

928− 1. Ask the baker what’s fresh

928+ 1. Ask the baker what's fresh

929 1. Buy the second-freshest batch

930- Cereal

931

932\

9331. First, separate eggs into a bowl

9341. Then, add a splash of cream

935− - If you don’t have cream, you can use milk, but cream is preferred

935+ - If you don't have cream, you can use milk, but cream is preferred

936− 1. If you don’t have milk or cream, melt an eighth of a stick of butter on

936+ 1. If you don't have milk or cream, melt an eighth of a stick of butter on

937 a skillet

938 1. Scramble the eggs in the bowl

939 1. Pour the eggs onto the skillet before the butter browns

@@ -956,26 +956,26 @@ destination.

956**Example:**

957

958```

959−[I’m an inline-style link](https://urbit.org/operations/#using-the-shell)

959+[I'm an inline-style link](https://urbit.org/operations/#using-the-shell)

960```

961

962**Produces:**

963

964−[I’m an inline-style link](https://urbit.org/operations/#using-the-shell)

964+[I'm an inline-style link](https://urbit.org/operations/#using-the-shell)

965

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

967−the current page’s location. Instead of the full url, we use `..` to fill in

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

968all of the URL that the destination has in common with the origin page.

969

970**Example:**

971

972```

973−[I’m a reference-style link](../shell)

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

974```

975

976**Produces:**

977

978−[I’m a reference-style link](../shell)

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

979

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

981examples should have the same destination.

@@ -997,9 +997,9 @@ Note that each HTML element `id` should be unique and not be used more than once

997```

998Check out this [section](#here-we-are) that we want to jump to.

999

1000−Four score and seven years ago …

1000+Four score and seven years ago ...

1001

1002−It was the best of times, it was the worst of times …

1002+It was the best of times, it was the worst of times ...

1003

1004## Here we are!

1005```

@@ -1008,16 +1008,16 @@ It was the best of times, it was the worst of times …

1008

1009Check out this [section](#here-we-are) that we want to jump to.

1010

1011−Four score and seven years ago …

1011+Four score and seven years ago ...

1012

1013−It was the best of times, it was the worst of times …

1013+It was the best of times, it was the worst of times ...

1014

1015## Here we are!

1016

1017### Double Quote

1018

1019Text enclosed in double quotes (`"`) will be rendered with

1020−opening and closing quotes -- that is, `“` and `”`.

1020+opening and closing quotes -- that is, `"` and `"`.

1021

1022**Example:**

1023```

@@ -1026,7 +1026,7 @@ opening and closing quotes -- that is, `“` and `”`.

1026

1027**Produces:**

1028

1029−“Yes,” he said. “That is the way with him.”

1029+"Yes," he said. "That is the way with him."

1030

1031### Code Literal

1032

@@ -1048,21 +1048,21 @@ inside a `<code>` HTML element with monospace font and highlighted with a

1048different background color.

1049

1050Using `` ` `` is useful when you want to designate only part of a line as code.

1051−Since this page is written in Udon, we’ve been using this operation

1051+Since this page is written in Udon, we've been using this operation

1052throughout this guide to _format text_ to distinguish `code` from prose.

1053

1054**Example:**

1055

1056```

1057−`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp’s `apply`.

1057+`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.

1058```

1059

1060**Produces:**

1061

1062−`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp’s `apply`.

1062+`*[a 2 b c] -> *[*[a b] *[a c]]` is like lisp's `apply`.

1063

1064Also, using the `++` prefix before a word will cause the word to be rendered as

1065−code with the `++` displayed, since that’s the standard notation for an arm in

1065+code with the `++` displayed, since that's the standard notation for an arm in

1066Hoon.

1067

1068**Example:**

@@ -1127,7 +1127,7 @@ Produces:\

1127### Horizontal Rule

1128

1129Three or more hyphens, such as `---`, on their own line produce an `<hr>`

1130−element, the “horizontal rule”. This is rendered as a horizontal line the

1130+element, the "horizontal rule". This is rendered as a horizontal line the

1131width of its containing paragraph.

1132

1133**Example:**

@@ -1211,7 +1211,7 @@ indent the text in question with **eight spaces**.

1211

1212## Sail Expressions

1213

1214−It’s possible to use Udon as an HTML templating language akin to

1214+It's possible to use Udon as an HTML templating language akin to

1215PHP, ERB, JSP, or Handlebars templates. This facility derives

1216in part from the support for embedding Hoon code inside the markup.

1217

@@ -1226,7 +1226,7 @@ Example:

1226```

1227;=

1228 ;p

1229− ;strong: Don’t panic!

1229+ ;strong: Don't panic!

1230 ;br;

1231 ;small: [reactive publishing intensifies]

1232 ==

@@ -1236,7 +1236,7 @@ Example:

1236Produces:

1237

1238<p>

1239− <strong>Don’t panic!</strong>

1239+ <strong>Don't panic!</strong>

1240 <br />

1241 <small>[reactive publishing intensifies]</small>

1242</p>

tutorials/ship-troubleshooting.md+23−23

@@ -5,7 +5,7 @@ template = "doc.html"

5aliases = ["docs/using/ship-troubleshooting/"]

6+++

8−Urbit is still in the development stage, so there’s a chance that your ship won’t start properly, or will stop working properly when you’re running it. That’s ok! This document is intended to help you in such an event.

8+Urbit is still in the development stage, so there's a chance that your ship won't start properly, or will stop working properly when you're running it. That's ok! This document is intended to help you in such an event.

10## Table of Contents

@@ -17,7 +17,7 @@ Urbit is still in the development stage, so there’s a chance that your ship wo

18## Best Practices {#best-practices}

20−An ounce of prevention is worth a pound of cure, so let’s first go over some best practices to keep your ship in working order.

20+An ounce of prevention is worth a pound of cure, so let's first go over some best practices to keep your ship in working order.

22### Only boot with your keyfile once

@@ -27,11 +27,11 @@ If you accidentally booted with the same keyfile twice, the only remedy is perfo

28### Do not delete your pier

30−Urbit is stateful, meaning that it needs to hold onto all your data. If you delete your pier and start your ship again, you won’t be able to talk to any ship you’ve talked to before. The only solution to this is performing a [personal breach](#personal-breach)

30+Urbit is stateful, meaning that it needs to hold onto all your data. If you delete your pier and start your ship again, you won't be able to talk to any ship you've talked to before. The only solution to this is performing a [personal breach](#personal-breach)

32### Keep track of the directory that you put your ship in

34−When you first start your ship, you should make sure you put it a place where you can find it again and where it won’t get accidentally deleted. Remember that you must perform `|mount %` in your ship’s Dojo to make your ship visible as a directory in the Unix file system.

34+When you first start your ship, you should make sure you put it a place where you can find it again and where it won't get accidentally deleted. Remember that you must perform `|mount %` in your ship's Dojo to make your ship visible as a directory in the Unix file system.

36### Avoid killing the urbit process directly

@@ -39,11 +39,11 @@ The best way to end an urbit process is to use `ctrl-d` from the Dojo. Unix meth

40### Keep up-to-date builds

42−Check for latest Urbit version at https://github.com/urbit/urbit/releases. If you’re behind, update using [this guide](@using/install.md).

42+Check for latest Urbit version at https://github.com/urbit/urbit/releases. If you're behind, update using [this guide](@using/install.md).

44−### `|hi` your star to see if you’re connected

44+### `|hi` your star to see if you're connected

46−Find out who your star is by running `(sein:title our now our)` in the Dojo. Then, run `|hi ~star`, where `~star` is the star’s name, and if things are working properly, you should get the message `hi ~star successful`. It could also be helpful to use `|hi` to check connectivity with `~zod` or another planet that you’re in a Chat channel with.

46+Find out who your star is by running `(sein:title our now our)` in the Dojo. Then, run `|hi ~star`, where `~star` is the star's name, and if things are working properly, you should get the message `hi ~star successful`. It could also be helpful to use `|hi` to check connectivity with `~zod` or another planet that you're in a Chat channel with.

48### Turn your ship off and on again

@@ -51,11 +51,11 @@ Use `ctrl-d` to gracefully exit your ship, and then start it again. This can sol

52### Use the `|knob` command to customize your error messages

54−Error messages can be by overwhelming, so the `|knob` command is intended to remedy this. It’s used to silence errors that aren’t important.

54+Error messages can be by overwhelming, so the `|knob` command is intended to remedy this. It's used to silence errors that aren't important.

56The command takes two arguments, and comes in the form of `|knob %error-tag %level`.

58−`%error-tag` is the name of the error in question. It’s usually printed at the top of the stack trace, such as in `crud: %hole event failed` -- `%hole` here is an example of an error tag.

58+`%error-tag` is the name of the error in question. It's usually printed at the top of the stack trace, such as in `crud: %hole event failed` -- `%hole` here is an example of an error tag.

60`%level` determines how much you will see of errors with your chosen `%error-tag`. There are three levels:

@@ -79,21 +79,21 @@ Run `|wash-gall`. This clears caches in Gall, and may result in steep performanc

80### My urbit is frozen

82−Sometimes this happens if you’re processing a very large event, or if you’re in an infinite loop, or for a variety of other reasons.

82+Sometimes this happens if you're processing a very large event, or if you're in an infinite loop, or for a variety of other reasons.

84−Before doing anything, try waiting for a minute: an event might finish processing. If it doesn’t clear up, then use the Unix kill-command, `ctrl-z`, to end your ship’s process. Then restart your ship.

84+Before doing anything, try waiting for a minute: an event might finish processing. If it doesn't clear up, then use the Unix kill-command, `ctrl-z`, to end your ship's process. Then restart your ship.

86### When I try to type into the Dojo, it prints `dy-noprompt`

88This happens when your Dojo is waiting on a request, such as an HTTP request. You can fix it simply by typing `backspace` or (`delete` on Mac).

90−### My ship doesn’t recognize file changes that I make in my pier

90+### My ship doesn't recognize file changes that I make in my pier

92−Since version `0.8.0`, changes no longer automatically sync between the Unix side (your pier) and your ship. To sync your file changes, you must run `|commit %desk` in your Dojo, where `%desk` is the desk you’d like to sync.

92+Since version `0.8.0`, changes no longer automatically sync between the Unix side (your pier) and your ship. To sync your file changes, you must run `|commit %desk` in your Dojo, where `%desk` is the desk you'd like to sync.

94## Connectivity Issues {#connectivity-issues}

96−### I can’t communicate with anyone

96+### I can't communicate with anyone

98You may have booted a ship with your keyfile twice in the same era. To fix this, you must perform a [personal breach](#personal-breach).

@@ -101,15 +101,15 @@ You may have booted a ship with your keyfile twice in the same era. To fix this,

101

102You may see a message like this one: `/~zod/home/~2019.7.22..18.55.46..83a3/sys/vane/ames:<[line column].[line column]>`. This is a clay path to a Hoon file, pointing to the line and column where an expression crashed. This kind of error might be accompanied by a `crud` message.

103

104−This means that another ship is sending invalid packets to you. This could be because one of the ships has not updated the other ship’s “life number,” which is the number that starts at one and increments every time that ship performs a personal breach.

104+This means that another ship is sending invalid packets to you. This could be because one of the ships has not updated the other ship's "life number", which is the number that starts at one and increments every time that ship performs a personal breach.

105

106−This can happen if they have the wrong keys of yours, or if you have the wrong keys of theirs. You can figure out who has the wrong keys by running this scry command in your dojo: `.^(* %j /=life=/shipname)`, where shipname is the other ship’s name. Save that information. Then, go to the [Azimuth contract on Etherscan](https://etherscan.io/address/0x223c067f8cf28ae173ee5cafea60ca44c335fecb#readContract), scroll down to `32. points`, and put in the hexadecimal representation of the other ship’s `@p`. You can find the hexadecimal representation by running …

106+This can happen if they have the wrong keys of yours, or if you have the wrong keys of theirs. You can figure out who has the wrong keys by running this scry command in your dojo: `.^(* %j /=life=/shipname)`, where shipname is the other ship's name. Save that information. Then, go to the [Azimuth contract on Etherscan](https://etherscan.io/address/0x223c067f8cf28ae173ee5cafea60ca44c335fecb#readContract), scroll down to `32. points`, and put in the hexadecimal representation of the other ship's `@p`. You can find the hexadecimal representation by running ...

107

108```

109`@ux`~sampel-palnet

110```

111

112−… in the Dojo, where `~sampel-palnet` is the other ship’s name. Then, compare it to the scry information that you saved. If that information matches up, it means that the other ship is the problem. If it **doesn’t** match up, your ship has wrong information about the other ship. If you have such wrong information, you can fix this by running:

112+... in the Dojo, where `~sampel-palnet` is the other ship's name. Then, compare it to the scry information that you saved. If that information matches up, it means that the other ship is the problem. If it **doesn't** match up, your ship has wrong information about the other ship. If you have such wrong information, you can fix this by running:

113

114```

115:azimuth-tracker|listen ~ %app %azimuth-tracker

@@ -125,13 +125,13 @@ The last line above syncs from an Ethereum node for _all_ ships on the network.

125

126The above commands work if you have the wrong keys of other ships. If other ships have wrong keys of _yours_, you need to somehow ask them to to run such a command.

127

128−### I can talk to some ships, but I can’t talk to my sponsor and some other ships

128+### I can talk to some ships, but I can't talk to my sponsor and some other ships

129

130This is the result of deleting your pier and starting your ship again. To fix this, you must perform a [personal breach](#personal-breach).

131

132## Booting Issues {#booting-issues}

133

134−### My ship won’t boot and gets a `terminals database is inaccessible` message

134+### My ship won't boot and gets a `terminals database is inaccessible` message

135

136This happens when you try to run the Urbit binary through your `$PATH`. When running the command, you need to be explicit and specify the actual path to it in the filesystem. This is a side-effect of the way we build the release binaries, which will be fixed.

137

@@ -139,7 +139,7 @@ This happens when you try to run the Urbit binary through your `$PATH`. When run

139

140You may have used the wrong arguments when booting your ship for the first time. Delete this comet and try again.

141

142−### My development ship (“fakezod”) gets a `boot: malformed` failure

142+### My development ship ("fakezod") gets a `boot: malformed` failure

143

144This means that you gave your development ship an invalid `@p`. So, you will get this error if you write, for example, `urbit -F zodzod` instead of `urbit -F zod`.

145

@@ -155,9 +155,9 @@ However, if you get a `bail` error again, you should perform a [personal breach]

155

156You can get help with you problem by creating an issue at [github.com/urbit/urbit](https://github.com/urbit/urbit/issues). But to make a good issue, you need to include some information.

157

158−When your urbit crashes with a `bail`, you’ll probably get a core dump, which is a file that contains the program state of your urbit when it crashed. On Mac, core dumps can be found in `/cores`. On Linux, cores can often be found in `/var/crash`, or the home directory.

158+When your urbit crashes with a `bail`, you'll probably get a core dump, which is a file that contains the program state of your urbit when it crashed. On Mac, core dumps can be found in `/cores`. On Linux, cores can often be found in `/var/crash`, or the home directory.

159

160−Navigate to the folder containing your core dumps. Find the most recent core dump by looking at the dates after you run `ls -l`. Then `lldb -c <corename>`. Once that loads, you’ll be at an `(lldb)` prompt; type `bt` at this prompt. This will create a stack trace that looks like this:

160+Navigate to the folder containing your core dumps. Find the most recent core dump by looking at the dates after you run `ls -l`. Then `lldb -c <corename>`. Once that loads, you'll be at an `(lldb)` prompt; type `bt` at this prompt. This will create a stack trace that looks like this:

161

162```

163(lldb) bt

@@ -176,7 +176,7 @@ Copy this stack trace and include it in your GitHub issue.

176

1771. Make sure you are running version to `0.8.2` if you are not already on it.

178

179−2. Restart your ship. If you don’t crash again, everything may be fine. If you **do** crash again, then you should perform a [personal breach](#personal-breach).

179+2. Restart your ship. If you don't crash again, everything may be fine. If you **do** crash again, then you should perform a [personal breach](#personal-breach).

180

181### My ship crashed with a `bail: oops` error

182