17b4884 · urbit.org · git.iko.soy

tutorials/hoon/_index.md+7−6

compare with master

unifiedsplit

@@ -24,12 +24,12 @@ Chapter 2 covers the type system, and writing apps, and the workings of the Arvo

24- [1.2 Nouns](nouns)

25- [1.3 Hoon Syntax](hoon-syntax)

26- [1.3.1 Walkthrough: Conditionals](conditionals)

27−- [1.4 Lists](lists)

28−- [1.4.1 Walkthrough: Fibonacci Sequence](fibonacci)

29−- [1.5 Gates (Hoon Functions)](gates)

27+- [1.4 Gates (Hoon Functions)](gates)

30−- [1.5.1 Walkthrough: Recursion](recursion)

28+- [1.4.1 Walkthrough: Recursion](recursion)

29+- [1.5 Lists](lists)

30+- [1.5.1 Walkthrough: Fibonacci Sequence](fibonacci)

31- [1.6 The Subject and Its Legs](the-subject-and-its-legs)

32−- [1.6.1 Walkthrough: Ackerman Function](ackermann)

32+- [1.6.1 Walkthrough: Ackermann Function](ackermann)

33- [1.7 Arms and Cores](arms-and-cores)

34- [1.7.1 Walkthrough: Caesar Cipher](caesar)

35- [1.8 Doors](doors)

@@ -52,6 +52,7 @@ Chapter 2 covers the type system, and writing apps, and the workings of the Arvo

52- [2.7.2 Gall: Async Monad](async-monad)

53- [2.8 Ford](ford)

54- [2.8.1 Walkthrough Ford Testing Suite Walkthrough](test-sets)

55+- [2.9.1 Walkthrough: Landscape Tile](landscape-tile)

55

56

57

57## Other Resources

58## Other Resources

@@ -63,4 +64,4 @@ Consult the [standard library documentation](@/docs/reference/library/_index.md)

63As you work your way through these lessons you may want to work on example problems from the [Hoon Workbook](@/docs/tutorials/hoon/workbook/_index.md) for practice. Once you finish the lessons here you may want to write more versatile Hoon programs which can make use of more of your urbit's environment, in which case you'll want to check out the [Generators](@/docs/tutorials/hoon/generators.md) documentation. Learn about [Udon and Sail](@/docs/tutorials/sail-and-udon.md), Urbit's stripped-down version of Markdown, and a subset of Hoon used for generating XML nodes respectively.

64As you work your way through these lessons you may want to work on example problems from the [Hoon Workbook](@/docs/tutorials/hoon/workbook/_index.md) for practice. Once you finish the lessons here you may want to write more versatile Hoon programs which can make use of more of your urbit's environment, in which case you'll want to check out the [Generators](@/docs/tutorials/hoon/generators.md) documentation. Learn about [Udon and Sail](@/docs/tutorials/sail-and-udon.md), Urbit's stripped-down version of Markdown, and a subset of Hoon used for generating XML nodes respectively.

64

65

66

66−> Last major revision of this section: October 2019

67+> Last major revision of this section: November 2019

tutorials/hoon/atoms-auras-and-simple-cell-types.md+1−1

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

18

19## Atoms and Auras

20

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

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

22

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

24

tutorials/hoon/bank-account.md+1−1

@@ -75,6 +75,6 @@ Each of these arms produces a gate which takes an `@ud` argument. Each of these

75+>.$(balance (add balance amount))

76```

77

78−`+>` is [wing syntax](/docs/reference/hoon-expressions/limb/limb/). This particularly wing construction looks for the the tail of the tail (the third element) in `$`, the subject of the gate we are in, which is the entire `new-account` door. We change `balance` to be the result of adding `balance` and `amount` and produce the door as the result. `withdraw` functions the same way only doing subtraction instead of addition.

78+`+>` is [wing syntax](@/docs/reference/hoon-expressions/limb/wing.md). This particularly wing construction looks for the the tail of the tail (the third element) in `$`, the subject of the gate we are in, which is the entire `new-account` door. We change `balance` to be the result of adding `balance` and `amount` and produce the door as the result. `withdraw` functions the same way only doing subtraction instead of addition.

79

80It's important to notice that the sample, `balance`, is stored as part of the door rather than existing outside of it.

tutorials/hoon/conditionals.md+2−2

@@ -20,7 +20,7 @@ In this lesson, we will write a generator that takes an integer and checks if it

20%.n

21```

22

23−On the very first line, with `:- %say` we are beginning to create a generator of the `%say` variety. The result of a `%say` generator is a cell with a head of `%say` and tail that is a gate, itself producing a `cask`, a pair of a `mark` and some data. It's not important for understanding conditionals; this is just template code. For more information about `%say` generators, see the [Generators](../generators) documentation.

23+On the very first line, with `:- %say` we are beginning to create a generator of the `%say` variety. The result of a `%say` generator is a cell with a head of `%say` and tail that is a gate, itself producing a `cask`, a pair of a `mark` and some data. It's not important for understanding conditionals; this is just template code. For more information about `%say` generators, see the [Generators](@/docs/tutorials/hoon/generators.md) documentation.

24

25```hoon

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

@@ -70,4 +70,4 @@ We only went into three "wut" runes in our walkthrough, but there are many other

70

71- `?|` takes an indefinite number of children. It's the logical "or" operator. It checks if at least one of its children is true.

72

73−To see an exhaustive list of "wut" runes, check out the [reference documentation on conditionals](/docs/reference/hoon-expressions/rune/wut/).

73+To see an exhaustive list of "wut" runes, check out the [reference documentation on conditionals](@/docs/reference/hoon-expressions/rune/wut.md).

tutorials/hoon/ford.md−2

@@ -4,8 +4,6 @@ weight = 38

4template = "doc.html"

5+++

6

7−# Ford

8−

9This lesson introduces the basics of the Ford vane, Arvo's build system and computation engine.

7This lesson introduces the basics of the Ford vane, Arvo's build system and computation engine.

10

8

11In terms of sheer size, Ford is Arvo's largest vane, weighing in at over 6000 lines of code at the time of writing. As a result, we will only be scratching the surface of Ford in this lesson. We will mostly focus on describing how Ford works in a broad sense and not dig too deeply into the details.

9In terms of sheer size, Ford is Arvo's largest vane, weighing in at over 6000 lines of code at the time of writing. As a result, we will only be scratching the surface of Ford in this lesson. We will mostly focus on describing how Ford works in a broad sense and not dig too deeply into the details.

tutorials/hoon/generators.md+1−2

@@ -26,8 +26,7 @@ a

26```

27

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

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

29+changes. Once you put this into a file named `echo.hoon` in the `/gen` directory, you must make your ship recognize the change by inputting `|commit %home` in the dojo. You can then run it from the dojo:

30−we can run it from the [Dojo](@/using/operations/_index.md):

31

30

32```

31```

33> +echo 42

32> +echo 42

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

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

84~zod

85```

86

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

88

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

90

@@ -124,7 +124,7 @@ 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 in special one-armed cores 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 in special one-armed cores called "gates". (We'll cover the role of `$` in [Lesson 1.4](@/docs/tutorials/hoon/gates.md).)

128

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

130

@@ -141,7 +141,7 @@ Wing expressions with multiple limbs are complex expressions. Examples:

141

142Hoon 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

@@ -307,16 +307,16 @@ Standard library functions are often built with other standard library functions

307

308## Reference Materials

309

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

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

311

312−- The [Runes](/docs/reference/hoon-expressions/) page will show you how to use any Hoon rune.

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

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

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

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

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

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

315+- 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.

316

317### Debugging

318

319−When you have an error in your Hoon code, one of two things can happen. Either the code does not run at all and you get an error (such as `nest-fail`), or your code _does_ run but produces the wrong results. The [Troubleshooting](/docs/reference/troubleshooting/) page is a good resource for figuring out how to debug your code.

319+When you have an error in your Hoon code, one of two things can happen. Either the code does not run at all and you get an error (such as `nest-fail`), or your code _does_ run but produces the wrong results. The [Troubleshooting](@/docs/reference/hoon-errors.md) page is a good resource for figuring out how to debug your code.

320

321There are a couple useful runes associated with debugging:

322

@@ -324,4 +324,4 @@ There are a couple useful runes associated with debugging:

324

325`~&` (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.

326

327−But there are more. Check out the aforementioned [troubleshooting](/docs/reference/troubleshooting/) page to see other handy debugging runes and how to use them.

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

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

@@ -129,4 +129,4 @@ Our program works by having each iteration of the list creating a cell. In each

129 4 ~

130```

131

132−If you still don't intuit how this is working, don't worry. We'll take a deeper look into recursion later with our [Recursion walkthrough](../recursion).

132+If you still don't intuit how this is working, don't worry. We'll take a deeper look into recursion later with our [Recursion Walkthrough](../recursion).

tutorials/hoon/nouns.md+1−1

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

283

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

285

286−You'll learn more about atoms and auras in [lesson 2.4](../atoms-auras-and-simple-cell-types.md).

286+You'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

tutorials/hoon/setup.md+2−2

@@ -18,7 +18,7 @@ These may not look like numbers, but they are. Each urbit name is written in a

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

20

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

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

22

23## Getting started

24

@@ -62,7 +62,7 @@ You'll see:

6217

63```

64

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 in [Chapter 1.2](@/docs/tutorials/hoon/nouns.md), but first let's write a very basic program.

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 in [Lesson 1.2](@/docs/tutorials/hoon/nouns.md), but first let's write a very basic program.

66

67## Generators

68

tutorials/hoon/structures-and-complex-types.md+1−1

@@ -352,5 +352,5 @@ Often `$@` is used to define a type with a null or trivial case for the `@` case

352

353Now the `~` value is included as a possible value for `user`.

354

355−That's all we have to say about types in this chapter. More on types in [Chapter 2](@/docs/tutorials/hoon/type-polymorphism.md).

355+We will see types arise again, in the context of polymorphism in [Lesson 2.5](@/docs/tutorials/hoon/type-polymorphism.md).

356

tutorials/hoon/test-sets.md−2

@@ -4,8 +4,6 @@ weight = 39

4template = "doc.html"

5+++

6

7−# Unit Testing with Ford

8−

9In this walkthrough we will show how to use Ford as a testing suite.

7In this walkthrough we will show how to use Ford as a testing suite.

10

8

11First we will cover the essential molds, arms, and generators used for testing, followed by walking through the code that implements a series of tests for standard library sets, as described [here](@/docs/tutorials/hoon/trees-sets-and-maps.md).

9First we will cover the essential molds, arms, and generators used for testing, followed by walking through the code that implements a series of tests for standard library sets, as described [here](@/docs/tutorials/hoon/trees-sets-and-maps.md).

tutorials/hoon/the-subject-and-its-legs.md+1−1

@@ -11,7 +11,7 @@ Hoon isn't an object-oriented programming language; it's a "subject-oriented" pr

11

12For now we can say three things about the subject: (1) every Hoon expression is evaluated relative to some subject; (2) roughly, the subject defines the environment in which a Hoon expression is evaluated; and (3) the subject is a noun.

13

14−In fact, you already learned about the noun address system in [Lesson 1.2](../nouns.md) when you used `+` to return a fragment of a noun:

14+In fact, you already learned about the noun address system in [Lesson 1.2](@/docs/tutorials/hoon/nouns.md) when you used `+` to return a fragment of a noun:

15

16```

17> +1:[[11 22] 33]

tutorials/hoon/trees-sets-and-maps.md+2−2

@@ -88,7 +88,7 @@ $(hay r.hay)

88

89## Sets

90

91−Use `set` to create a data structure for a set of values, e.g., `(set @)` for a set of atoms. The `in` core in the Hoon standard library contains the various functions for operating on sets. See the standard library reference documentation for sets [here](/docs/reference/library/2h/).

91+Use `set` to create a data structure for a set of values, e.g., `(set @)` for a set of atoms. The `in` core in the Hoon standard library contains the various functions for operating on sets. See the standard library reference documentation for sets [here](@/docs/reference/library/2h/).

92

93As with `list`s and `tree`s, there are two categories of sets: null `~`, and non-null. Hoon implements sets using trees for the underlying noun.

94

@@ -237,7 +237,7 @@ Use `map` to create a set of key-value pairs, e.g., `(map @tas *)` for a set of

237

238One example use case is for storing customer information as a set of pairs: `(map [employee-name employee-data])`.

239

240−The `by` core in the Hoon standard library contains the various functions for operating on maps. Many of these functions are similar to the set functions of the `in` core. See the standard library reference documentation for maps here [here](/docs/reference/library/2i/). As was the case with sets, the underlying noun of each map is a tree.

240+The `by` core in the Hoon standard library contains the various functions for operating on maps. Many of these functions are similar to the set functions of the `in` core. See the standard library reference documentation for maps [here](@/docs/reference/library/2i/). As was the case with sets, the underlying noun of each map is a tree.

241

242Two common methods for populating a map include (1) creating it from a list of key-value cells using the `my` function, and (2) inserting items into a map using the `put` arm of the `by` core.

243