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

git.iko.soy/urbit.org

fixed broken links, updated hoon tutorial chaptering

commit9c671ac9f0b2ab147d9e3b89ebf046ba83888cbc authorRobert <robert@tlon.io> dateFri 18 Jan 2019, 16:46 (8 years ago) parentee7d842

21 files changed+61−47

compare with master

unifiedsplit

learn/arvo/hoon.udon+3−3

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

2323

2424## Lessons

2525

26−;list;

26+-

2727

2828## Other Resources

2929

30−Consult the [Reference](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.

3131

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.

3333

3434> Last major revision of this section: December 2018

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

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

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

22 navuptwo/'true'

33 next/'true'

4− sort/'24'

4+ sort/'14'

55 title/'Arms and Cores'

66 ==

77;>

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

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

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

22 navuptwo/'true'

33 next/'true'

4− sort/'30'

4+ sort/'24'

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

66 ==

77;>

9−# Atoms, Auras, and Simple Cell Types

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

1010

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

1212

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

2222

2323## Atoms and Auras

2424

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

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

2626

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

2828

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

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

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

22 navuptwo/'true'

33 next/'true'

4− sort/'34'

4+ sort/'26'

55 title/'Cores Again'

66 ==

77;>

9−# Cores Again

9+# 2.6 Cores Again

1010

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

1212

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

153153

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

155155

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

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

157157

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

159159

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

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

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

22 navuptwo/'true'

33 next/'true'

4− sort/'33'

4+ sort/'27'

55 title/'Cores'

66 ==

77;>

9−# Cores

9+2.7 Cores

1010

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

1212

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

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

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

22 navuptwo/'true'

33 next/'true'

4− sort/'37'

4+ sort/'30'

55 title/'Examples'

66 ==

77;>

9−# Examples

9+# 2.10 Examples

1010

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

1212

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

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

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

22 navuptwo/'true'

33 next/'true'

4− sort/'25'

4+ sort/'15'

55 title/'Gates (Hoon Functions)'

66 ==

77;>

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

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

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

22 navuptwo/'true'

33 next/'true'

4− sort/'21'

4+ sort/'11'

55 title/'Getting Started'

66 ==

77;>

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

1212

1313## Installing Urbit

1414

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

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

1616

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

1818

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

2626

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

2828

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

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

3030

3131## Booting a Comet

3232

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

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

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

22 navuptwo/'true'

33 next/'true'

4− sort/'27'

4+ sort/'21'

55 title/'Hoon Programs'

66 ==

77;>

9−# Writing Hoon Programs

9+# 2.1 Writing Hoon Programs

1010

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

1212

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

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

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

22 navuptwo/'true'

33 next/'true'

4− sort/'28'

4+ sort/'22'

55 title/'Hoon Syntax'

66 ==

77;>

9−# Hoon Syntax

9+# 2.2 Hoon Syntax

1010

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

1212

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

93930b1101.1001

9494```

9595

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

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

9797

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

9999

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

160160

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

162162

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

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

164164

165165#### Tall and Flat Forms

166166

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

264264

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

266266

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

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

268268

269269```

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

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

30830835

309309```

310310

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

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

312312

313313### Expressions That Are Only Irregular

314314

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

349349[16 18]

350350```

351351

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

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

353353

354354## Hoon Style

355355

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

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

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

22 navuptwo/'true'

33 next/'true'

4− sort/'35'

4+ sort/'28'

55 title/'Standard Library: Lists'

66 ==

77;>

9−# Standard Library: Lists

9+# 2.8 Standard Library: Lists

1010

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

1212

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

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

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

22 navuptwo/'true'

33 next/'true'

4− sort/'26'

4+ sort/'16'

55 title/'Multi-gate Cores and Doors'

66 ==

77;>

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

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

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

22 navuptwo/'true'

33 next/'true'

4− sort/'22'

4+ sort/'12'

55 title/'Nouns'

66 ==

77;>

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

290290

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

292292

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

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

294294

295295## Cells

296296

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

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

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

22 navuptwo/'true'

33 next/'true'

4− sort/'29'

4+ sort/'23'

55 title/'Simple One-Gate Programs'

66 ==

77;>

9−# Simple One-Gate Programs

9+# 2.3 Simple One-Gate Programs

1010

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

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

1212

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

1414

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

2020

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

2222

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

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

2424

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

2626

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

630630

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

632632

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

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

634634

635635### Decrement

636636

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

732732

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

734734

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

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

736736

737737```

738738|= end=@ :: 1

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

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

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

22 navuptwo/'true'

33 next/'true'

4− sort/'32'

4+ sort/'25'

55 title/'Structures and Complex Types'

66 ==

77;>

9−# Structures and Complex Types

9+# 2.5 Structures and Complex Types

1010

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

1212

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

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

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

22 navuptwo/'true'

33 next/'true'

4− sort/'23'

4+ sort/'13'

55 title/'The Subject and Its Legs'

66 ==

77;>

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

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

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

22 navuptwo/'true'

33 next/'true'

4− sort/'36'

4+ sort/'29'

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

66 ==

77;>

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

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

1010

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

1212

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

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

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

22 navuptwo/'true'

33 next/'true'

4− sort/'31'

4+ sort/'24'

55 title/'Type Checking and Type Inference'

66 ==

77;>

9−# Type Checking and Type Inference

9+# 2.4 Type Checking and Type Inference

1010

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

1212

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

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

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

22 navuptwo/'true'

3− sort/'38'

3+ sort/'31'

44 title/'Type Polymorphism'

55 ==

66;>

8−# Polymorphism

8+# 2.11 Polymorphism

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

1111

reference.udon+9

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

77# Reference

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

10+

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

12+

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

14+help demystify our jargon.

15+

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

17+

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

reference/hoon-expressions/advanced.udon+5

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

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

120120*bivariant*.

121121

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

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

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

125+safety.)

126+

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

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

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