9c671ac · urbit.org · git.iko.soy

learn/arvo/hoon.udon+3−3

compare with master

unifiedsplit

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

23

24## Lessons

25

26−;list;

26+-

27

28## Other Resources

29

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

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

31

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

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

33

34> Last major revision of this section: December 2018

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

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'24'

4+ sort/'14'

5 title/'Arms and Cores'

6 ==

7;>

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

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'30'

4+ sort/'24'

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

6 ==

7;>

8

9−# Atoms, Auras, and Simple Cell Types

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

10

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

12

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

22

23## Atoms and Auras

24

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

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

26

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

28

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

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'34'

4+ sort/'26'

5 title/'Cores Again'

6 ==

7;>

8

9−# Cores Again

9+# 2.6 Cores Again

10

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

12

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

153

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

155

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

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

157

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

159

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

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'33'

4+ sort/'27'

5 title/'Cores'

6 ==

7;>

8

9−# Cores

9+2.7 Cores

10

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

12

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

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'37'

4+ sort/'30'

5 title/'Examples'

6 ==

7;>

8

9−# Examples

9+# 2.10 Examples

10

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

12

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

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'25'

4+ sort/'15'

5 title/'Gates (Hoon Functions)'

6 ==

7;>

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

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'21'

4+ sort/'11'

5 title/'Getting Started'

6 ==

7;>

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

12

13## Installing Urbit

14

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

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

16

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

18

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

26

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

28

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

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

30

31## Booting a Comet

32

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

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'27'

4+ sort/'21'

5 title/'Hoon Programs'

6 ==

7;>

8

9−# Writing Hoon Programs

9+# 2.1 Writing Hoon Programs

10

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

12

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

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'28'

4+ sort/'22'

5 title/'Hoon Syntax'

6 ==

7;>

8

9−# Hoon Syntax

9+# 2.2 Hoon Syntax

10

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

12

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

930b1101.1001

94```

95

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

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

97

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

99

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

160

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

162

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

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

164

165#### Tall and Flat Forms

166

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

264

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

266

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

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

268

269```

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

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

30835

309```

310

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

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

312

313### Expressions That Are Only Irregular

314

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

349[16 18]

350```

351

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

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

353

354## Hoon Style

355

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

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'35'

4+ sort/'28'

5 title/'Standard Library: Lists'

6 ==

7;>

8

9−# Standard Library: Lists

9+# 2.8 Standard Library: Lists

10

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

12

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

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'26'

4+ sort/'16'

5 title/'Multi-gate Cores and Doors'

6 ==

7;>

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

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'22'

4+ sort/'12'

5 title/'Nouns'

6 ==

7;>

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

290

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

292

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

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

294

295## Cells

296

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

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'29'

4+ sort/'23'

5 title/'Simple One-Gate Programs'

6 ==

7;>

8

9−# Simple One-Gate Programs

9+# 2.3 Simple One-Gate Programs

10

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

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

12

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

14

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

20

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

22

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

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

24

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

26

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

630

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

632

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

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

634

635### Decrement

636

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

732

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

734

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

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

736

737```

738|= end=@ :: 1

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

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'32'

4+ sort/'25'

5 title/'Structures and Complex Types'

6 ==

7;>

8

9−# Structures and Complex Types

9+# 2.5 Structures and Complex Types

10

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

12

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

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'23'

4+ sort/'13'

5 title/'The Subject and Its Legs'

6 ==

7;>

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

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'36'

4+ sort/'29'

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

6 ==

7;>

8

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

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

10

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

12

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

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

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

2 navuptwo/'true'

3 next/'true'

4− sort/'31'

4+ sort/'24'

5 title/'Type Checking and Type Inference'

6 ==

7;>

8

9−# Type Checking and Type Inference

9+# 2.4 Type Checking and Type Inference

10

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

12

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

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

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

2 navuptwo/'true'

3− sort/'38'

3+ sort/'31'

4 title/'Type Polymorphism'

5 ==

6;>

7

8−# Polymorphism

8+# 2.11 Polymorphism

9

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

11

reference.udon+9

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

7# Reference

8

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

10+

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

12+

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

14+help demystify our jargon.

15+

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

17+

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

reference/hoon-expressions/advanced.udon+5

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

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

120*bivariant*.

121

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

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

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

125+safety.)

126+

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

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

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

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

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

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