09325ae · urbit.org · git.iko.soy

tutorials/arvo/ames.md+5−5

compare with master

unifiedsplit

@@ -88,7 +88,7 @@ number. Messages on the same path are guaranteed to arrive in the same

88order as they were sent. No such guarantees are made across paths.

89

90The `r` is the actual data that you are sending. As the type implies,

91−this can be an arbitrary noun, and it will be transferred to the

91+this can be an arbitrary [noun](/docs/glossary/noun/), and it will be transferred to the

92receiver exactly as-is, in a well-typed way. Of course, this is data

93that is sent over the wire, so be careful not to send anything too

94massive unless you're willing to wait.

@@ -104,7 +104,7 @@ directly into `++wise:am`.

104 zork:zank:(wool:(ho:(um p.soq) q.soq) hen cha val ete)

105```

106

107−The inputs to this gate are exactly the sort of thing you'd expect. In

107+The inputs to this [gate](/docs/glossary/gate/) are exactly the sort of thing you'd expect. In

108particular, everything in the `%wont` gate is here plus the calling duct

109so that we know where to send the acknowledgment and `ete` to determine

110if we're going to do the modern end-to-end acknowledgments.

@@ -113,7 +113,7 @@ The actual line of code looks intimidating, but it's really not all that

113bad. Working from the inside out, the call to `++um` sets up our

114domestic server, and the call to `++ho` sets up our knowledge about the

115neighbor we're sending to. From the outside, `++zork` and `++zank` just

116−apply the changes made to our `++um` and `++am` cores, respectively. If

116+apply the changes made to our `++um` and `++am` [cores](/docs/glossary/core/), respectively. If

117you're familiar with the common idiom of `++abet`, that's all this is.

118The code predates the widespread usage of that name.

119

@@ -162,7 +162,7 @@ crypto. At the moment, we only need our neighbor's life, which we put

162into the meal.

163

164Finally, we call `++wind:ho:um:am` with the `++soup` of the path and

165−message number and the `++meal:ames` of the payload itself. For end-to-end

165+message number and the `++meal:ames` of the [payload](/docs/glossary/payload/) itself. For end-to-end

166acknowledged messages, we use `%bund`.

167

168```hoon

@@ -204,7 +204,7 @@ actual, 1KB packets.

204```

205

206For organizational purposes, `++zuul` constructs an internal core with

207−three arms. `++wasp` encodes the meal into an atom with no encryption.

207+three [arms](/docs/glossary/arm/). `++wasp` encodes the meal into an [atom](/docs/glossary/atom/) with no encryption.

208`++wisp` encodes a meal with possible encryption (else it simply calls

209`++wasp`). `++weft` takes the result of `++wisp` and splits it into

210actual packets.

tutorials/arvo/arvo.md+4−4

@@ -76,7 +76,7 @@ In mathematical terms, one may think of Arvo as being given by a transition func

76T: (State, Input) -> (State, Output).

77```

78

79−In practice, _T_ is implemented by the `+poke` arm of the Arvo kernel, which is described in more detail in the [kernel section](#the-kernel). In theoretical terms, it may be more practical to think of Arvo as being defined by a _lifecycle function_ we denote here by _L_:

79+In practice, _T_ is implemented by the `+poke` [arm](/docs/glossary/arm/) of the Arvo kernel, which is described in more detail in the [kernel section](#the-kernel). In theoretical terms, it may be more practical to think of Arvo as being defined by a _lifecycle function_ we denote here by _L_:

80

81```

82L: History -> State.

@@ -120,7 +120,7 @@ the user experience is akin to that of a web browser.

120

121### Event log

122

123−The formal state of an Arvo instance is an event history, as a linked list of nouns from first to last. The history starts with a bootstrap sequence that delivers Arvo itself, first as an inscrutable kernel, then as the self-compiling source for that kernel. After booting, we break symmetry by delivering identity and entropy. The rest of the log is actual input.

123+The formal state of an Arvo instance is an event history, as a linked list of [nouns](/docs/glossary/noun/) from first to last. The history starts with a bootstrap sequence that delivers Arvo itself, first as an inscrutable kernel, then as the self-compiling source for that kernel. After booting, we break symmetry by delivering identity and entropy. The rest of the log is actual input.

124

125The Arvo event log is a list of every action ever performed on your ship that

126lead up to the current state. In principle, this event log is maintained by the

@@ -247,7 +247,7 @@ This section requires an understanding of Hoon of at least the level of Chapter

247

248## Overall structure

249

250−`arvo.hoon` contains five top level cores as well as a "formal interface" consisting of a single gate that implements the transition function. They are nested with the `=<` and `=>` runes like so, where items lower on the list are contained within items higher on the list:

250+`arvo.hoon` contains five top level cores as well as a "formal interface" consisting of a single [gate](/docs/glossary/gate/) that implements the transition function. They are nested with the `=<` and `=>` runes like so, where items lower on the list are contained within items higher on the list:

251 + Types

252 + Section 3bE Arvo Core

253 + Implementation core

@@ -475,7 +475,7 @@ stage or adult stage). Thus when `+poke` is performed, a new core with the

475updated state it produced, rather than modifying the existing core as would be

476expected to happen in an imperative setting.

477

478−Thus besides the battery of the Arvo core, we have the payload which is as

478+Thus besides the battery of the Arvo core, we have the [payload](/docs/glossary/payload/) which is as

479follows.

480

481```hoon

tutorials/arvo/clay.md+4−4

@@ -24,7 +24,7 @@ foreign ships.

24## Architecture

25

26Clay is the primary filesystem for the arvo operating system,

27−which is the core of an urbit. The architecture of clay is

27+which is the [core](/docs/glossary/core/) of an urbit. The architecture of clay is

28intrinsically connected with arvo, but we assume no knowledge of

29either arvo or urbit. We will point out only those features of

30arvo that are necessary for an understanding of clay, and we will

@@ -207,7 +207,7 @@ convert back to `%txt`. The diff, patch, and merge algorithms are

207fairly straightforward for json, though they're very different

208from the text ones.

209

210−More formally, a mark is a core with three arms, `++grab`,

210+More formally, a mark is a core with three [arms](/docs/glossary/arm/), `++grab`,

211`++grow`, and `++grad`. In `++grab` is a series of functions to

212convert from other marks to the given mark. In `++grow` is a

213series of functions to convert from the given mark to other

@@ -922,7 +922,7 @@ very limited usefulness, and is not used at the moment.

922which is your classic diff. We, however, will work on any list of data.

923

924`%d` refers to changes in a tree of data. This is general enough to

925−describe changes to any hoon noun, but often more special-purpose delta

925+describe changes to any hoon [noun](/docs/glossary/noun/), but often more special-purpose delta

926should be created for different content types. This is not used at the

927moment, and may in fact be unimplemented.

928

@@ -2442,7 +2442,7 @@ We'll examine `++knit` and `++wake`, in that order.

2442 ==

2443```

2444

2445−This is kind of a long gate, but don't worry, it's not bad at all.

2445+This is kind of a long [gate](/docs/glossary/gate/), but don't worry, it's not bad at all.

2446

2447First, we assert that we're not a domestic desk. That wouldn't make any

2448sense at all.

tutorials/arvo/eyre.md+4−4

@@ -57,7 +57,7 @@ From arvo, requests enter `++call`, which after some type reification are passed

57along to `++apex:ye`. In the case of a `%this` task, its components are

58parsed(see `++zest:epur`, `++eat-headers`) and handed off to `++handle`, wrapped

59in `++emule` to produce a `++fail` page in case of error. `++apex:handle` will

60−`++process` the request to a `pest` or a `++done` core, and in the former case

60+`++process` the request to a `pest` or a `++done` [core](/docs/glossary/core/), and in the former case

61`++resolve` the pest into an outgoing card.

62

63XX it also seems to affect the current ship, test that serving ship name is consistently correct

@@ -95,7 +95,7 @@ XX `%cast %mime` used to be in ford-get-beam, is there a reason it was removed?

95## Back into the breach, or: auxilary requests

96

97Now, it was mentioned that this result is self-refreshing: the `%urb`

98−translation door injects a `;script@"/~/on/{deps}.js"` into every page, `deps`

98+translation [door](/docs/glossary/door/) injects a `;script@"/~/on/{deps}.js"` into every page, `deps`

99is a ford-readable hash of the set of resources that page construction depended

100on.

101

@@ -409,7 +409,7 @@ To this object, `/main/lib/urb.js` adds helpers:

409- `send({data,mark?='json',app?=urb.app,ship?}, cb?)` delivers messages

410- `bind({path,app?=urb.app}, cb)` subscribes by path

411- `drop({path,app?=urb.app}, cb?)` pulls the subscription

412−- `util` is an object containing methods for converting between JavaScript types and Hoon atom odors.

412+- `util` is an object containing methods for converting between JavaScript types and Hoon [atom](/docs/glossary/atom/) odors.

413

414## 3. Requests

415

@@ -538,7 +538,7 @@ Signs a `%writ` upon change.

538

539### 5.4 `[%f %exec (unit silk)]`, functional transformations

540

541−The `%f` interface converts nouns from one form to another. An empty unit represents cancellation.

541+The `%f` interface converts [nouns](/docs/glossary/noun/) from one form to another. An empty unit represents cancellation.

542

543Signs a `%made` containing the computation result.

544

tutorials/arvo/ford.md+3−3

@@ -93,7 +93,7 @@ functionality. We don't usually have naked hoods outside ford.

93

94### `%reef`

95

96−Produces a core containing the entirety of Zuse and Hoon, suitable for

96+Produces a [core](/docs/glossary/core/) containing the entirety of Zuse and Hoon, suitable for

97running arbitrary code against. The mark is `%noun`.

98

99### `%ride`

@@ -402,7 +402,7 @@ Wide-form unfiltered `/_` doesn't need a delimiter: `/= kids /_/hoon/`

402### `/_` filtered: run a horn on each file in the directory matching an aura

403

404Filtered `/_` takes an aura and a horn, and filters the list of files in the

405−current directory by whether their filenames can be parsed to an atom of that

405+current directory by whether their filenames can be parsed to an [atom](/docs/glossary/atom/) of that

406aura. It then produces a map where each key is the filename after parsing into

407that atom type, and each value is the result of running the horn on the

408contents of that file.

@@ -420,7 +420,7 @@ Wide-form filtered `/_` uses `_` as a delimiter: `/= timed-posts /_@da_/md/`

420

421### `/;` "fasmic"

422

423−`/;` takes a twig and a horn. The twig should evaluate to a gate, which is then slammed

423+`/;` takes a twig and a horn. The twig should evaluate to a [gate](/docs/glossary/gate/), which is then slammed

424with the result of the horn as its sample.

425

426Example:

tutorials/arvo/gall.md+2−2

@@ -61,7 +61,7 @@ definable in a regular recursive data type).

61

62## Specification

63

64−An agent is defined as a core with a set of arms to handle various

64+An agent is defined as a [core](/docs/glossary/core/) with a set of [arms](/docs/glossary/arm/) to handle various

65events. These handlers usually produce a list of effects and the next

66state of the agent. The interface definition can be found in

67`sys/zuse.hoon`, which at the time of writing is:

@@ -361,7 +361,7 @@ the subscription.

361### Vases and cages

362

363A `vase` is a piece of dynamic data. Structurally, it's a pair of an

364−explicit reification of a type and an untyped noun. This lets us

364+explicit reification of a type and an untyped [noun](/docs/glossary/noun/). This lets us

365represent a value which has a type that isn't known at compile time. A

366vase has three operations:

367

tutorials/concepts/technical-overview.md+2−2

@@ -122,8 +122,8 @@ and Nock are two layers: Hoon, the practical layer, compiles itself to Nock, the

122simple layer. Your urbit runs in Vere, which includes a Nock interpreter, so it

123can upgrade Hoon over the network without downtime.

124

125−The Nock data model is quite simple. Every piece of data is a 'noun'. A noun

125+The Nock data model is quite simple. Every piece of data is a 'noun'. A [noun](/docs/glossary/noun/)

126−is an atom or a cell. An atom is any unsigned integer. A cell is an ordered

126+is an [atom](/docs/glossary/atom/) or a cell. An atom is any unsigned integer. A cell is an ordered

127pair of nouns. Nouns are acyclic and expose no pointer equality test.

128

129### Vere

tutorials/hoon/_index.md+1−1

@@ -12,6 +12,6 @@ Before you start, we recommend reading [Why Hoon?](https://urbit.org/blog/why-ho

12

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

14

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**, which are an important data structure in Hoon. Once you get the hang of cores 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.

16

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

tutorials/hoon/ackermann.md+1−1

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

7

8The Ackermann function is one of the earliest examples of a function that is both totally computable -- meaning that it can be solved -- and not primitively recursive -- meaning it can not be rewritten in an iterative fashion.

9

10−In this lesson, we will write a gate that computes the [Ackermann function](https://en.wikipedia.org/wiki/Ackermann_function)

10+In this lesson, we will write a [gate](/docs/glossary/gate/) that computes the [Ackermann function](https://en.wikipedia.org/wiki/Ackermann_function)

11

12``` hoon

13|= [m=@ n=@]

tutorials/hoon/arms-and-cores.md+4−4

@@ -4,7 +4,7 @@ weight = 15

4template = "doc.html"

5aliases = ["/docs/learn/hoon/hoon-tutorial/arms-and-cores/"]

6+++

7−The Hoon subject is a noun. Each fragment of this noun is either an arm or a leg. In the previous lesson you learned what a leg is, and how to return legs of the subject by various means. In this lesson you'll learn what an arm is. Arms are a bit more complex than legs -- a full understanding of them requires a bit more background knowledge. Accordingly, in this lesson we must also introduce an important Hoon data structure: a 'core'.

7+The Hoon subject is a [noun](/docs/glossary/noun/). Each fragment of this [noun](/docs/glossary/noun/) is either an [arm](/docs/glossary/arm/) or a leg. In the previous lesson you learned what a leg is, and how to return legs of the subject by various means. In this lesson you'll learn what an [arm](/docs/glossary/arm/) is. Arms are a bit more complex than legs -- a full understanding of them requires a bit more background knowledge. Accordingly, in this lesson we must also introduce an important Hoon data structure: a '[core](/docs/glossary/core/)'.

8

9After arms are defined and explained we review wing expressions, this time focusing on wing resolution to arms.

10

@@ -14,9 +14,9 @@ Arms and legs are limbs of the subject, i.e., noun fragments of the subject. In

14

15An **arm** is some expression of Hoon encoded as a noun. (By 'encoded as a noun' we literally mean: 'compiled to a Nock formula'. But you don't need to know anything about Nock to understand Hoon.) You virtually never need to treat an arm as raw data, even though technically you can -- it's just a noun like any other. You virtually always want to think of an arm simply as a way of running some Hoon code.

16

17−Every expression of Hoon is evaluated relative to a subject. What subject is the arm to be evaluated against? Answer: the parent core of that arm.

17+Every expression of Hoon is evaluated relative to a subject. What subject is the arm to be evaluated against? Answer: the parent [core](/docs/glossary/core/) of that arm.

18

19−So in order to understand fully what an arm is, you must understand what a core is. Briefly, a **core** is a cell of `[battery payload]`. The **battery** is a collection of one or more arms, and the **payload** is the data needed by the arms to evaluate correctly. (The battery is code and the payload is data for that code.) A given core is the **parent core** of all of the arms in its battery.

19+So in order to understand fully what an arm is, you must understand what a core is. Briefly, a **core** is a cell of `[battery payload]`. The **battery** is a collection of one or more arms, and the **payload** is the data needed by the arms to evaluate correctly. (The battery is code and the [payload](/docs/glossary/payload/) is data for that code.) A given core is the **parent core** of all of the arms in its battery.

20

21## Your First Core

22

@@ -110,7 +110,7 @@ Now use the following multi-line expression to bind `c` to a core. As before, f

110

111Note: binding `c` to the core created by the `|%` expression will fail unless you have already bound `a` and `b` to the relevant values, as we did above. Our having already bound them is what lets us use them in the `|%` expression.

112

113−The `|%` expression above creates a core with four arms. The first, named `two`, evaluates to the constant `2`. The second arm, `inc`, adds `1` to `a`. `double` returns double the value of `a`, and `sum` returns the sum of the two atoms in `b`. The computations defined by these arms are pretty simple (and in the case of `two`, trivial), but a good starting point for learning about cores.

113+The `|%` expression above creates a core with four arms. The first, named `two`, evaluates to the constant `2`. The second arm, `inc`, adds `1` to `a`. `double` returns double the value of `a`, and `sum` returns the sum of the two [atoms](/docs/glossary/atom/) in `b`. The computations defined by these arms are pretty simple (and in the case of `two`, trivial), but a good starting point for learning about cores.

114

115Let's run the arm names in the dojo:

116

tutorials/hoon/async-monad.md+2−2

@@ -158,7 +158,7 @@ The following code is from `app/example-tapp-fetch.hoon` Much of this file shoul

158--

159```

160

161−As indicated by the comments, `handle-poke` is the main arm of our Gall app. This is equivalent to the `poke` arms in a standard Gall app, but will not differentiate by mark. Let's look at the first part of this gate.

161+As indicated by the comments, `handle-poke` is the main [arm](/docs/glossary/arm/) of our Gall app. This is equivalent to the `poke` arms in a standard Gall app, but will not differentiate by mark. Let's look at the first part of this [gate](/docs/glossary/gate/).

162

163```hoon

164++ handle-poke

@@ -212,4 +212,4 @@ In a number of cases `D` here is going to be another `;<` rune. This is how you

212

213Continuing on, here is a use of `fetch-json` with the `;<` that is an example worth reading. `fetch-json` takes a `tape` and produces a `form:(async ,json)` which can be processed to obtain the data we want.

214

215−Armed with an understanding of `;<`, the rest of `handle-poke` should be quite readable though you may need to consult the `dejs-soft:format` core to get a firm grasp on how JSON parsing works. Hopefully, you now have an understanding of the basic use of the `tapp` library. This style of Gall app can result in code that, while potentially less flexible, is easier to read and reason about than a traditional Gall app.

215+Armed with an understanding of `;<`, the rest of `handle-poke` should be quite readable though you may need to consult the `dejs-soft:format` [core](/docs/glossary/core/) to get a firm grasp on how JSON parsing works. Hopefully, you now have an understanding of the basic use of the `tapp` library. This style of Gall app can result in code that, while potentially less flexible, is easier to read and reason about than a traditional Gall app.

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

@@ -6,7 +6,7 @@ aliases = ["/docs/learn/hoon/hoon-tutorial/atoms-auras-and-simple-cell-types/"]

6+++

7Like 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_%28computer_science%29)) won't be addressed until a later chapter.

8

9−A type is ordinarily understood to be a set of values. Examples: the set of all atoms is a type, the set of all cells is a type, and so on.

9+A type is ordinarily understood to be a set of values. Examples: the set of all [atoms](/docs/glossary/atom/) is a type, the set of all cells is a type, and so on.

10

11Type systems provide type safety, in part by making sure functions produce values of the correct type. When you write a function whose product is intended to be an atom, it would be nice to know that the function is guaranteed to produce an atom. Hoon's type system provides such guarantees with **type checking** and **type inference**.

12

@@ -52,7 +52,7 @@ Let's try one in the dojo. For the expression to be assessed we'll use `15` aga

5215

53```

54

55−Because `@ud` is the inferred type of `15`, the cast succeeds. Notice that the `^-` expression never does anything to modify the underlying noun of the second subexpression. It's used simply to mandate a type-check on that expression. This check occurs at compile-time (i.e., when the expression is compiled to Nock).

55+Because `@ud` is the inferred type of `15`, the cast succeeds. Notice that the `^-` expression never does anything to modify the underlying [noun](/docs/glossary/noun/) of the second subexpression. It's used simply to mandate a type-check on that expression. This check occurs at compile-time (i.e., when the expression is compiled to Nock).

56

57What about when the inferred type doesn't fit under the cast type? You get a `nest-fail` crash at compile-time:

58

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

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

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

6+++

7

8−In this lesson, we will write a door that can act as a bank account with the ability to withdraw, deposit, and check the account's balance.

8+In this lesson, we will write a [door](/docs/glossary/door/) that can act as a bank account with the ability to withdraw, deposit, and check the account's balance.

9

10```hoon

11:- %say

@@ -38,7 +38,7 @@ We start with the three lines we have in every `%say` generator:

38:- %noun

39```

40

41−In the above code chunk, we're creating a cell. The head of this cell is `%say`. The tail is a gate (`|= *`) that produces another cell (`:- %noun`) with a head of the mark of a the kind of data we are going to produce, a noun; the tail of the second cell is the rest of the program.

41+In the above code chunk, we're creating a cell. The head of this cell is `%say`. The tail is a [gate](/docs/glossary/gate/) (`|= *`) that produces another cell (`:- %noun`) with a head of the mark of a the kind of data we are going to produce, a [noun](/docs/glossary/noun/); the tail of the second cell is the rest of the program.

42

43```hoon

44=< =~ new-account

@@ -51,7 +51,7 @@ In the above code chunk, we're creating a cell. The head of this cell is `%say`.

51

52In this code above, we're going to compose two runes using `=<`, which has inverted arguments. We use this rune to keep the heaviest twig to the bottom of the code.

53

54−`=~` is a rune that composes multiple expressions. We take `new-account` and use that as the subject for the call to `deposit`. `deposit` and `withdraw` both produce a new version of the door that's used in subsequent calls, which is why we are able to chain them in this fashion. The final reference is to `balance`, which is the account balance contained in the core we that that we examine below.

54+`=~` is a rune that composes multiple expressions. We take `new-account` and use that as the subject for the call to `deposit`. `deposit` and `withdraw` both produce a new version of the door that's used in subsequent calls, which is why we are able to chain them in this fashion. The final reference is to `balance`, which is the account balance contained in the [core](/docs/glossary/core/) we that that we examine below.

55

56```hoon

57|%

@@ -67,7 +67,7 @@ In this code above, we're going to compose two runes using `=<`, which has inver

67--

68```

69

70−We've chosen here to wrap our door in its own core to emulate the style of programming that is used when creating libraries. `new-account` is the name of our door. Recall that a door is a core with one or more arms that has a sample. Here, our door has a sample of one `@ud` with the face `balance` and two arms, `deposit` and `withdraw`.

70+We've chosen here to wrap our door in its own core to emulate the style of programming that is used when creating libraries. `new-account` is the name of our door. Recall that a door is a core with one or more [arms](/docs/glossary/arm/) that has a sample. Here, our door has a sample of one `@ud` with the face `balance` and two arm `deposit` and `withdraw`.

71

72Each of these arms produces a gate which takes an `@ud` argument. Each of these gates has a similar bit of code inside:

73

tutorials/hoon/behn.md+1−1

@@ -20,7 +20,7 @@ Notably, vanes are _not_ something that a user ever interacts with directly. The

20

21## Behn

22

23−In this section we introduce the simplest Arvo vane, Behn. This is not exhaustive, but just enough to know what is going on inside of Behn when we make a system call to it in the egg timer app. We discuss relevant types, some arms that are only called internally, and arms that may be called by another vane via a `move`.

23+In this section we introduce the simplest Arvo vane, Behn. This is not exhaustive, but just enough to know what is going on inside of Behn when we make a system call to it in the egg timer app. We discuss relevant types, some [arms](/docs/glossary/arm/) that are only called internally, and arms that may be called by another vane via a `move`.

24

25Behn is an Arvo vane that acts as a simple timer. It allows vanes and applications to set timer events, which are managed in a simple priority queue.

26

tutorials/hoon/caesar.md+6−6

@@ -122,16 +122,16 @@ itself before reading the explanation.

122The `!:` in the first line of the above code enables a full stack trace in the

123event of an error.

124

125−`|= [msg=tape key=@ud]` creates a gate that takes a cell. The head of this cell

125+`|= [msg=tape key=@ud]` creates a [gate](/docs/glossary/gate/) that takes a cell. The head of this cell

126is a `tape`, which is a string type that's a list of `cord`s. Tapes are represented

127as text surrounded by double-quotes, such as this: `"a tape"`. We give this input

128−tape the face `msg`. The tail of our cell is a `@ud` -- an unsigned decimal atom

128+tape the face `msg`. The tail of our cell is a `@ud` -- an unsigned decimal [atom](/docs/glossary/atom/)

129-- that we give the face `key`.

130

131`=<` is the rune that evaluates its first child expression with respect to its

132second child expression as the subject. In this case, we evaluate the

133−expressions in the code chunk below against the core declared later, which

133+expressions in the code chunk below against the [core](/docs/glossary/core/) declared later, which

134−allows us reference the core's contained arms before they are defined. Without

134+allows us reference the core's contained [arms](/docs/glossary/arm/) before they are defined. Without

135`=<`, we would need to put the code chunk below at the bottom of our program.

136

137```hoon

@@ -209,13 +209,13 @@ value. A `map` is a type equivalent to a dictionary in other languages: it's a

209data structure that associates a key with a value. If, for example, we wanted

210to have an association between `a` and 1 and `b` and 2, we could use a `map`.

211

212−`=| chart=(map @t @t)` adds a noun to the subject with the default value of

212+`=| chart=(map @t @t)` adds a [noun](/docs/glossary/noun/) to the subject with the default value of

213the `(map @t @t)` type, and gives that noun the face `chart`.

214

215`?. =((lent a) (lent b))` checks if the two tapes are the same length. If not,

216the program crashes.

217

218−`|-` creates a trap, a gate that is called immediately.

218+`|-` creates a [trap](/docs/glossary/trap/), a gate that is called immediately.

219

220`?: |(?=(~ a) ?=(~ b))` checks if either tape is empty. If this is true, we

221the program is finished and can return `chart`, the the `map` that we have been

tutorials/hoon/conditionals.md+3−3

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

18==

19```

20

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

21+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](/docs/glossary/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.

22

23```hoon

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

25```

26

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

28

29```hoon

30:- %noun

@@ -85,7 +85,7 @@ Of course, doing so would be needlessly obfuscating - we mention this only to il

85

86- `?!` ("wut-zup") 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.

87

88−- `?@` takes three children. It branches on whether its first child is an atom.

88+- `?@` takes three children. It branches on whether its first child is an [atom](/docs/glossary/atom/).

89

90- `?^` takes three children. It branches on whether its first child is a cell.

91

tutorials/hoon/doors.md+4−4

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

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

6+++

7

8−It's useful to have cores whose arms evaluate to make gates. The use of such cores is common in Hoon; that's how the functions of the Hoon standard library are stored in the subject. Learning about such cores will also deepen the reader's understanding of Hoon semantics, and for that reason alone is worthwhile.

8+It's useful to have [cores](/docs/glossary/core/) whose [arms](/docs/glossary/arm/) evaluate to make [gates](/docs/glossary/gate/). The use of such cores is common in Hoon; that's how the functions of the Hoon standard library are stored in the subject. Learning about such cores will also deepen the reader's understanding of Hoon semantics, and for that reason alone is worthwhile.

9

10In this lesson you'll also learn about a new kind of core, called a 'door'.

11

@@ -210,9 +210,9 @@ Here are some of the other gates that can be generated from this core in the Hoo

210

211## Doors

212

213−A brief review: A core is a cell of battery and payload: `[battery payload]`. The battery is code and the payload is data. The battery contains a series of arms, and the payload contains all the data necessary to run those arms correctly.

213+A brief review: A core is a cell of battery and [payload](/docs/glossary/payload/): `[battery payload]`. The battery is code and the payload is data. The battery contains a series of arms, and the payload contains all the data necessary to run those arms correctly.

214

215−New material: A **door** is a core with a sample. That is, a door is a core whose payload is a cell of sample and context: `[sample context]`.

215+New material: A **door** is a core with a sample. That is, a [door](/docs/glossary/door/) is a core whose payload is a cell of sample and context: `[sample context]`.

216

217```

218 Door

@@ -250,7 +250,7 @@ The first subexpression after the `|_` rune defines the door's sample. (This is

250

251#### Back to the Example

252

253−For the door defined above, `c`, the sample is defined as an atom, `@`, and given the face `b`. The `plus` arm defines a gate that takes a single atom as its argument, `a`, and which returns the sum of `a` and `b`. The `times` arm defines a gate that takes a single atom, `a`, and returns `a` times `b`. The `greater` arm defines a gate that takes a single atom, `a`, and if `a` is greater than `b` returns `%.y`; otherwise `%.n`.

253+For the door defined above, `c`, the sample is defined as an [atom](/docs/glossary/atom/), `@`, and given the face `b`. The `plus` arm defines a gate that takes a single [atom](/docs/glossary/atom/) as its argument, `a`, and which returns the sum of `a` and `b`. The `times` arm defines a gate that takes a single [atom](/docs/glossary/atom/), `a`, and returns `a` times `b`. The `greater` arm defines a gate that takes a single [atom](/docs/glossary/atom/), `a`, and if `a` is greater than `b` returns `%.y`; otherwise `%.n`.

254

255Let's try out the arms of `c` with ordinary function calls:

256

tutorials/hoon/egg-timer.md+3−3

@@ -54,7 +54,7 @@ You can find the full definition of `bowl` in `sys/zuse.hoon`, but for now it's

54- `eny` Guaranteed-fresh entropy

55- `now` The current time

56

57−The `door` we've made has two arms `poke-noun` and `wake`. Gall is capable of dispatching `pokes`, or requests, to an app based on the mark of the data given along with that poke. These are sent to the arm with the name that matches the mark of the data. Here we use the generic `noun` mark:

57+The `door` we've made has two [arms](/docs/glossary/arm/) `poke-noun` and `wake`. Gall is capable of dispatching `pokes`, or requests, to an app based on the mark of the data given along with that poke. These are sent to the [arm](/docs/glossary/arm/) with the name that matches the mark of the data. Here we use the generic `noun` mark:

58

59```hoon

60++ poke-noun

@@ -64,13 +64,13 @@ The `door` we've made has two arms `poke-noun` and `wake`. Gall is capable of di

64 [ost %wait /egg-timer (add now t)]

65```

66

67−In the above code, we create a gate that takes a single `@dr` argument. `@dr` is an aura for a 128-bit relative date. Here are a few examples.

67+In the above code, we create a [gate](/docs/glossary/gate/) that takes a single `@dr` argument. `@dr` is an aura for a 128-bit relative date. Here are a few examples.

68

69- `~s17` 17 seconds

70- `~m20` 20 minutes

71- `~d42` 42 days

72

73−As a matter of good type hygiene, we explicitly cast the output of this gate with `^+` to ensure we are producing the correct thing for Gall to handle. `^+` is the rune for casting by example. Our example is a cell: `list` of `move`, which we `bunt` with `*`, is the head; `+>.$`, the enclosing core which is our `door`, is the tail.

73+As a matter of good type hygiene, we explicitly cast the output of this gate with `^+` to ensure we are producing the correct thing for Gall to handle. `^+` is the rune for casting by example. Our example is a cell: `list` of `move`, which we `bunt` with `*`, is the head; `+>.$`, the enclosing [core](/docs/glossary/core/) which is our `door`, is the tail.

74

75Next we're going to use the `:_` rune which is just the inverted form a `:-` the cell construction rune. We use it twice so the actual data will end up looking something like:

76

tutorials/hoon/fibonacci.md+2−2

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

21==

22```

23

24−On the first line, we use `|=` to produce a gate which takes an `@ud` that's stored in the face `n`. This `n` sample that we give our 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` members, the program ends.

25

26```hoon

27%- flop

@@ -58,4 +58,4 @@ In the code above, `?:` checks whether the first child, `=(i n)`, our terminatin

58==

59```

60

61−The final expression in our program calls the `$` arm of the trap we are in but makes some changes: we increment `i`, set `p` to be `q` and `q` becomes the sum of `p` and `q`. `r` becomes a cell of `q` and whatever `r` was previously. The list built from this is the one that will get `flop`ped to produce the result at the end of the computation.

61+The final expression in our program calls the `$` [arm](/docs/glossary/arm/) of the [trap](/docs/glossary/trap/) we are in but makes some changes: we increment `i`, set `p` to be `q` and `q` becomes the sum of `p` and `q`. `r` becomes a cell of `q` and whatever `r` was previously. The list built from this is the one that will get `flop`ped to produce the result at the end of the computation.

tutorials/hoon/ford.md+3−3

@@ -91,7 +91,7 @@ It is important for us to note that Ford is _not_ used to build vanes. Vanes are

91

92## Using Ford

93

94−Having covered the distinctive features of Ford, we now dive into some of the specifics on how these features are implemented. Let us first cover some of most important types of data we will run into, and then discuss the most frequently used arms.

94+Having covered the distinctive features of Ford, we now dive into some of the specifics on how these features are implemented. Let us first cover some of most important types of data we will run into, and then discuss the most frequently used [arms](/docs/glossary/arm/).

95

96### Data types

97

@@ -113,8 +113,8 @@ A `schematic`, found in `zuse.hoon`, is a set of build instruction for Ford. It

113

114Some examples of subtypes include:

115 - `%list` - a list of schematics to build.

116− - `%core` - a Clay path to a Hoon source file to build.

116+ - `%[core](/docs/glossary/core/)` - a Clay path to a Hoon source file to build.

117− - `%call` - a schematic consisting of two sub-schematics, one of which produces a gate and a second that produces a sample. It then runs the gate on the sample, producing a vase of the result, tagged with the mark `%noun`.

117+ - `%call` - a schematic consisting of two sub-schematics, one of which produces a [gate](/docs/glossary/gate/) and a second that produces a sample. It then runs the [gate](/docs/glossary/gate/) on the sample, producing a vase of the result, tagged with the mark `%noun`.

118 - `%scry` - look up a value from the Urbit namespace.

119

120 Schematics are only ever sent to Ford by another vane. Userspace apps do not directly create schematics.

tutorials/hoon/gall.md+4−4

@@ -9,9 +9,9 @@ Gall is the Arvo vane responsible for handling user space applications. When wri

9

10## bowl and moves

11

12−The core of a gall app is a door which has two parts of its subject, the first a `bowl:gall` which contains a lot of standard things used by gall apps, the second a type containing app state information.

12+The [core](/docs/glossary/core/) of a gall app is a [door](/docs/glossary/door/) which has two parts of its subject, the first a `bowl:gall` which contains a lot of standard things used by gall apps, the second a type containing app state information.

13

14−Vanes in Arvo communicate by means of `moves`. When a move is produced by an arm in a gall app, it's dispatched by Arvo to the correct handler for the request, be it another application or another vane. A `move` is pair of `bone` and `card`. These are essential components to understand when learning to use gall.

14+Vanes in Arvo communicate by means of `moves`. When a move is produced by an [arm](/docs/glossary/arm/) in a gall app, it's dispatched by Arvo to the correct handler for the request, be it another application or another vane. A `move` is pair of `bone` and `card`. These are essential components to understand when learning to use gall.

15

16A `bone` is an opaque cause that initiates a request. When constructing a `move` you can often use `ost.bowl` and when responding to an incoming `move` you can use the `bone` in that `move` to construct your response.

17

@@ -26,7 +26,7 @@ A `card` is the effect or event that is being requested. Each application should

26 ==

27```

28

29−Each `card` is a pair of a tag and a noun. The tag indicates what the event being triggered is and the noun is any data required for that event.

29+Each `card` is a pair of a tag and a [noun](/docs/glossary/noun/). The tag indicates what the event being triggered is and the [noun](/docs/glossary/noun/) is any data required for that event.

30

31## Arms

32

@@ -34,7 +34,7 @@ Gall applications can have a number of arms that get called depending on the inf

34

35### ++prep

36

37−`++prep` is the arm that is called when an application is first started or when it's updated. This arm should be a gate that takes a `unit` of a noun and provides a way, if necessary, to make any changes to the application's data required by an upgrade. As a reminder, a `unit` is a type that may contain another type or it might contain `~`. They are used when there may or may not be some data available.

37+`++prep` is the arm that is called when an application is first started or when it's updated. This arm should be a [gate](/docs/glossary/gate/) that takes a `unit` of a noun and provides a way, if necessary, to make any changes to the application's data required by an upgrade. As a reminder, a `unit` is a type that may contain another type or it might contain `~`. They are used when there may or may not be some data available.

38

39Often when developing an application you will not initially care about the data. Here is a sample `++prep` arm that will simply throw away the previous application state.

40

tutorials/hoon/gates.md+4−4

@@ -12,7 +12,7 @@ The word 'function' is used in various ways, but let's start by talking about th

12

13That 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

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

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

17You'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

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

28

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

30

31−A gate is a core with two distinctive properties: (1) the battery of a gate contains exactly one arm, which has the special name `$`. The `$` 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 of the gate correctly.

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

33```

34Gate: [$ [Sample Context]]

@@ -48,7 +48,7 @@ Like all arms, `$` is computed with its parent core as the subject. When `$` is

48

49## Creating Your First Gate

50

51−Let's make a gate that takes any unsigned integer (i.e., an 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':

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

53```

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

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

93

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

95

96−The pretty printer represents the `$` arm of `inc` as `1.jgn`. To see the actual noun of the `$` arm, enter `+2:inc` into the dojo:

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

98```

99> +2:inc

tutorials/hoon/generators.md+6−6

@@ -16,7 +16,7 @@ There are four kinds of generators: naked, `%say`, `%get`, and `%ask`.

16### Naked Generators

17

18A naked generator is simply a `gate`; that is, it is an anonymous function that

19−takes a `sample` (argument) and produces a noun. All you need to do is write a

19+takes a `sample` (argument) and produces a [noun](/docs/glossary/noun/). All you need to do is write a

20`gate` and put it into a file in the `/gen` directory. Let's take a look at a

21very simple one:

22

@@ -49,7 +49,7 @@ an `aura` is type metadata and does other things, too.

49

50In the example above, we didn't specify an `aura`, leaving the printer to fend

51for itself. `"asdf"` is a `tape`, a type that is simply a `list` of `cords`. A

52−`cord` is itself an atom represented as a string of UTF-8 characters. When used

52+`cord` is itself an [atom](/docs/glossary/atom/) represented as a string of UTF-8 characters. When used

53as part of a `tape`, the `cord` is only a single character. So each atom in the

54`[97 115 100 102 0]` output corresponds to a component of the `tape`: 97 is

55`a`, 115 is `s`, 100 is `d`, 102 is `f`, and `0` is the "null" that every list

@@ -141,7 +141,7 @@ the `|= *` expression on the line that follows.

141(add 40 2)

142```

143

144−`|= *` constructs a gate that takes a noun. This gate will itself produce a

144+`|= *` constructs a [gate](/docs/glossary/gate/) that takes a noun. This [gate](/docs/glossary/gate/) will itself produce a

145`cask`, which is cell formed by the prepending `:-`. The head of that `cask` is

146`%noun` and the tail is the rest of the program, `(add 40 2)`. The tail of the

147`cask` will be our actual data produced by the body of the program: in this

@@ -230,8 +230,8 @@ In the code, our sample specifies faces on all of the Arvo data, meaning that we

230can easily access them. We also require the argument `[n=@ud ~]`, and allow the

231_optional_ argument `[bet=@ud ~]`.

232

233−But there's something new: `(~(rad og eny) n)`. This code pulls the `rad` arm

233+But there's something new: `(~(rad og eny) n)`. This code pulls the `rad` [arm](/docs/glossary/arm/)

234−out of the `og` core with the subject of `eny`. Recall that `eny` is our entropy

234+out of the `og` [core](/docs/glossary/core/) with the subject of `eny`. Recall that `eny` is our entropy

235value, so this is used to seed the generator. The `rad` arm will give us a

236pseudorandom number between 0 and `n`. Then we form a cell with the result and

237`bet`, the optional named argument specified previously.

@@ -601,4 +601,4 @@ result of the generator.

601

602## Conclusion

603

604−You've now reached the end of Chapter 1 of the Hoon tutorial. Ideally you should have a fair understanding of the fundamental concepts of subject-oriented programming: limbs, legs, faces, wings, arms, cores, gates, and doors. If you can master these concepts you should have little or no trouble learning to write substantial Hoon programs.

604+You've now reached the end of Chapter 1 of the Hoon tutorial. Ideally you should have a fair understanding of the fundamental concepts of subject-oriented programming: limbs, legs, faces, wings, arms, cores, gates, and [doors](/docs/glossary/door/). If you can master these concepts you should have little or no trouble learning to write substantial Hoon programs.

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

@@ -57,11 +57,11 @@ An [expression](https://en.wikipedia.org/wiki/Expression_%28computer_science%29

57

58Hoon 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**).

59

60−There are many categories of Hoon expressions: 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.

61

62### Noun Literals

63

64−A noun is either an atom or a cell. An 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.

65

66There 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.

67

@@ -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](/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

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

130

@@ -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 (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

tutorials/hoon/iron-polymorphism.md+3−3

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

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

6+++

7

8−Polymorphism is a programming concept that allows a a piece of code to use different types at different times. It's a common technique in most languages to make code that can be reused for many different situations, and Hoon is no exception. Let's take a look at a gate from the Hoon standard library as an example; we'll be passing a few different types in. The code below is an excerpt from `hoon.hoon` and, as such, will not run as-is by itself.

8+Polymorphism is a programming concept that allows a a piece of code to use different types at different times. It's a common technique in most languages to make code that can be reused for many different situations, and Hoon is no exception. Let's take a look at a [gate](/docs/glossary/gate/) from the Hoon standard library as an example; we'll be passing a few different types in. The code below is an excerpt from `hoon.hoon` and, as such, will not run as-is by itself.

9

10`fold` is a _wet_ gate that takes two arguments and produces a _dry_ gate. But what are wet and dry gates?

11

12−A dry gate (also simply a _gate_) is the kind that you're already familiar with by now: a one-armed core with a sample. A wet gate is also a one-armed core with a sample, but there is a difference. With a dry gate, when you pass in an argument and the code gets compiled, the type system will try to cast to the type specified by the gate; if you pass something that does not fit in the specified type, for example a `cord` instead of a `cell` you will get a nest failure. On the other hand, when you pass arguments to a wet gate, their types are preserved and type analysis is done at the definition site of the gate -- in our case, `fold` in `hoon.hoon` -- rather than the call site.

12+A dry gate (also simply a _gate_) is the kind that you're already familiar with by now: a one-armed [core](/docs/glossary/core/) with a sample. A wet gate is also a one-armed [core](/docs/glossary/core/) with a sample, but there is a difference. With a dry gate, when you pass in an argument and the code gets compiled, the type system will try to cast to the type specified by the gate; if you pass something that does not fit in the specified type, for example a `cord` instead of a `cell` you will get a nest failure. On the other hand, when you pass arguments to a wet gate, their types are preserved and type analysis is done at the definition site of the gate -- in our case, `fold` in `hoon.hoon` -- rather than the call site.

13

14```hoon

15++ fold

@@ -21,7 +21,7 @@ A dry gate (also simply a _gate_) is the kind that you're already familiar with

21 $(xs t.xs, st (f st i.xs))

22```

23

24−On the first line of the arm, we use `|*` to create a wet gate, with two arguments: `state` and `elem`. These arguments are both `mold`s; that is to say, they are type definitions. We use this to define the types used in the dry gate.

24+On the first line of the [arm](/docs/glossary/arm/), we use `|*` to create a wet gate, with two arguments: `state` and `elem`. These arguments are both `mold`s; that is to say, they are type definitions. We use this to define the types used in the dry gate.

25

26```hoon

27|= [[st=state xs=(list elem)] f=$-([state elem] state)]

tutorials/hoon/landscape-tile.md+3−3

@@ -220,7 +220,7 @@ window.testingTile = testingTile;

220

221### Default Code Components

222

223−Parts of the `testing.hoon` code shown above is the "scaffolding" that was automatically built for us by the default Hoon file from the `create-landscape-app` repo. We'll give a general overview of those arms here.

223+Parts of the `testing.hoon` code shown above is the "scaffolding" that was automatically built for us by the default Hoon file from the `create-landscape-app` repo. We'll give a general overview of those [arms](/docs/glossary/arm/) here.

224

225As with other gall apps, `card` and `move` define the types that can be produced by the app, `card` specifically defines which type of requests can be made to other parts of the system.

226

@@ -257,11 +257,11 @@ Now that we've glanced at the default components of the program, lets take a clo

257 ==

258```

259

260−`++poke-json` is going to accept a `json` and produce a `quip`. A `quip` is a pair of: a list of `moves` (in this case), and some state which is the same type as the core we are building. To be clear, a `json` in Hoon is not the same thing as something in the more general JSON format. It is rather a parsed data structure.

260+`++poke-json` is going to accept a `json` and produce a `quip`. A `quip` is a pair of: a list of `moves` (in this case), and some state which is the same type as the [core](/docs/glossary/core/) we are building. To be clear, a `json` in Hoon is not the same thing as something in the more general JSON format. It is rather a parsed data structure.

261

262There are several uses of the `~&` rune. These are simply debugging printfs that we can skip over.

263

264−`(om:dejs:format same)` builds a gate that converts a `json` into a `map`.

264+`(om:dejs:format same)` builds a [gate](/docs/glossary/gate/) that converts a `json` into a `map`.

265

266`++so:dejs:format` formats some piece of data out of the `json` map, in this case the value of `%ship`. `sthu` is transformed by [`slaw`](@/docs/reference/library/4m.md#slaw) into an actual `@p` to verify that we didn't get sent nonsense. If we did, `need` will cause the gate to crash.

267

tutorials/hoon/lead-polymorphism.md+5−5

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

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

6+++

7

8−There are four kinds of cores: gold, iron, zinc, and lead. You are able to use core-variance rules to create programs which take other programs as arguments. Which particular rules depends on which kind of core your program needs to complete.

8+There are four kinds of [cores](/docs/glossary/core/): gold, iron, zinc, and lead. You are able to use core-variance rules to create programs which take other programs as arguments. Which particular rules depends on which kind of core your program needs to complete.

9

10−Lead cores have opaque payloads. That is, the payload can not be written to or read from. Below is an example of using lead cores. The program produces a list populated by the first 10 elements of `fib`.

10+Lead cores have opaque [payloads](/docs/glossary/payload/). That is, the payload can not be written to or read from. Below is an example of using lead cores. The program produces a list populated by the first 10 elements of `fib`.

11

12```hoon

13=< (to-list (take fib 10))

@@ -57,7 +57,7 @@ Lead cores have opaque payloads. That is, the payload can not be written to or r

57--

58```

59

60−There are five arms in this core: `stream`, `stream-type`, `to-list`, `take`, and `fib`.

60+There are five [arms](/docs/glossary/arm/) in this core: `stream`, `stream-type`, `to-list`, `take`, and `fib`.

61

62

63```hoon

@@ -68,11 +68,11 @@ There are five arms in this core: `stream`, `stream-type`, `to-list`, `take`, an

68 ~

69```

70

71−`stream` is a mold-builder. It's a wet gate that takes one argument, `of`, which is a `mold`, and produces a trap -- a function with no argument.

71+`stream` is a mold-builder. It's a wet gate that takes one argument, `of`, which is a `mold`, and produces a [trap](/docs/glossary/trap/) -- a function with no argument.

72

73`$_` is a rune that produces a type from an example; `^?` converts (casts) a core to lead; `|.` forms the trap. So to follow this sequence we read it backwards: we create a trap, convert it to a lead trap (making its payload inaccessible), and then use that lead trap as an example to produce a type from.

74

75−With the line `^- $@(~ [item=of more=^$])`, the output of the trap will be cast into a new type. `$@` is the rune to describe a data structure that can either be an atom or a cell. The first part describes the atom, which here is going to be `~`. The second part describes a cell, which we define to have the head of type `of` with the face `item`, and a tail with a face of `more`. The expression `^$` is not a rune, but rather a reference to the enclosing wet gate, so the tail of this cell will be of the same type produced by this wet gate.

75+With the line `^- $@(~ [item=of more=^$])`, the output of the trap will be cast into a new type. `$@` is the rune to describe a data structure that can either be an [atom](/docs/glossary/atom/) or a cell. The first part describes the [atom](/docs/glossary/atom/), which here is going to be `~`. The second part describes a cell, which we define to have the head of type `of` with the face `item`, and a tail with a face of `more`. The expression `^$` is not a rune, but rather a reference to the enclosing wet [gate](/docs/glossary/gate/), so the tail of this cell will be of the same type produced by this wet [gate](/docs/glossary/gate/).

76

77The final `~` here is used as the type produced when initially calling this wet gate. This is valid because it nests within the type we defined on the previous line.

78

tutorials/hoon/libraries.md+3−3

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

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

6+++

7

8−In Hoon, like in other languages, it's often useful to create a library for other code to access. In this example, we look at one example of a library that can be used to represent a deck of 52 playing cards. The core below builds such a library, and can be accessed by programs.

8+In Hoon, like in other languages, it's often useful to create a library for other code to access. In this example, we look at one example of a library that can be used to represent a deck of 52 playing cards. The [core](/docs/glossary/core/) below builds such a library, and can be accessed by programs.

9

10```hoon

11|%

@@ -62,7 +62,7 @@ In Hoon, like in other languages, it's often useful to create a library for othe

62

63On the very first line, we create a core with `|%`. This core contains all of our library code, and is closed by the `--` on the final line.

64

65−To create three types we're going to need, we use `+$`, which is an arm used to define a type.

65+To create three types we're going to need, we use `+$`, which is an [arm](/docs/glossary/arm/) used to define a type.

66

67

68```hoon

@@ -91,7 +91,7 @@ One way to get a feel for how a library works is to skim the `++` arm-names befo

91 ==

92```

93

94−We can see this is a gate that takes a single `@ud` and produces a `suit`.

94+We can see this is a [gate](/docs/glossary/gate/) that takes a single `@ud` and produces a `suit`.

95

96The `?+` rune is the rune to switch against a value with a default. The default here is to crash with `!!`. Then we have the four options of 1 through 4, based on the value of `val`, which each resulting in a different suit.

97

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

@@ -44,9 +44,9 @@ There's a few things going on in our first line. The first part of it, `|=`, is

44

45All 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.

46

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

47+The 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.

48

49−Because we're only on line 1, all we're doing with the gate is creating it, and then specifying what kind of input the gate takes with that rune's first child: `end=@`. The `end` part of our code is simply a name that we give to the user's input so that we can use the number later. `=@` means that we restrict the kind of input that our gate accepts to the **atom** type, or `@` for short. An atom is a natural number.

49+Because we're only on line 1, all we're doing with the gate is creating it, and then specifying what kind of input the gate takes with that rune's first child: `end=@`. The `end` part of our code is simply a name that we give to the user's input so that we can use the number later. `=@` means that we restrict the kind of input that our gate accepts to the **atom** type, or `@` for short. An [atom](/docs/glossary/atom/) is a natural number.

50

51Our program is simple, so the _entire program_ is the gate that's being created here. The rest of our lines of code are part of the second child of our gate, and they determine how our gate produces an output.

52

tutorials/hoon/lists.md+3−3

@@ -7,13 +7,13 @@ aliases = ["/docs/learn/hoon/hoon-tutorial/lists/"]

7

8# Lists

9

10−A **list** is a type of 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).

10+A **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).

11

12So 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:

13

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

15

16−It's easy to see where the heads are and where the nesting tails are. The head of the above list is the atom `1` and the tail is the list `[2 [3 [4 ~]]]`, (or `[2 3 4 ~]`). Recall that 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.

16+It's easy to see where the heads are and where the nesting tails are. The head of the above list is the [atom](/docs/glossary/atom/) `1` and the tail is the list `[2 [3 [4 ~]]]`, (or `[2 3 4 ~]`). Recall that 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.

17

18To make a list, let's cast nouns to the `(list @)` ("list of atoms") type.

19

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

119

120#### `flop` Exercise 1.5a

121

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

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.

123

124### `sort`

125

tutorials/hoon/molds.md+2−2

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

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

6+++

7

8−A mold is a function that coerces a noun to a type or crashes.

8+A mold is a function that coerces a [noun](/docs/glossary/noun/) to a type or crashes.

9

10Let's take some examples from `hoon.hoon`. `|$` is a new rune as of the writing of this document so you may see this spelled in slightly different way if you don't have the latest version of `hoon.hoon`. `|$` is the mold builder rune which takes a list of molds and produces a mold.

11

@@ -32,7 +32,7 @@ Here is a very simple mold builder. It takes two molds and produces a mold that

32 |$ [item]

33 $@(~ [i=item t=(list item)])

34```

35−Here is a mold builder you've used previously. `$@` is a rune that will match the first thing if its sample is an atom and the second if the sample is a cell. You should be familiar at this point that a `list` is either `~` or a pair of an item and a list of item.

35+Here is a mold builder you've used previously. `$@` is a rune that will match the first thing if its sample is an [atom](/docs/glossary/atom/) and the second if the sample is a cell. You should be familiar at this point that a `list` is either `~` or a pair of an item and a list of item.

36

37

38```hoon

tutorials/hoon/nouns.md+2−2

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

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

6+++

7

8−In Urbit, every piece of data is a 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.

9

10## Noun Definition

11

12−A **noun** is either an 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.

13

14Here are some atoms:

15

tutorials/hoon/recursion.md+3−3

@@ -37,7 +37,7 @@ Next we check to see if `n` is `1`. If so, the result is just `1`, since

37

38If, however, `n` is _not_ `1`, then we branch to the final line of the code,

39`(mul n $(n (dec n)))`, where the recursion logic lives. Here, we multiply `n`

40−by the recursion of `n` minus `1`. `$` initiates recursion: it calls the gate

40+by the recursion of `n` minus `1`. `$` initiates recursion: it calls the [gate](/docs/glossary/gate/)

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

42

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

@@ -138,7 +138,7 @@ $(n (dec n), t (mul t n))

138The above code should look familiar. We are still building a gate that

139takes one argument `n`. This time, however, we are also putting a face on a

140`@ud` and setting its initial value to 1. The `|-` here is used to create a new

141−gate with one arm `$` and immediately call it. Think of `|-` as the recursion

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

142point.

143

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

@@ -175,7 +175,7 @@ each iteration can be replaced instead of held in memory.

175#### A Note on `$`

176

177`$` (pronounced "buc") is, in its use with recursion, a reference to the gate that we are inside

178−of. That's because a gate is just a core with a single arm named `$`. The

178+of. That's because a gate is just a [core](/docs/glossary/core/) with a single arm named `$`. The

179subject is searched depth-first, head before tail, with faces skipped, and

180stopping on the first result. In other words, the first match found in the head

181will be returned. If you wished to refer to the outer `$` in this context, the

tutorials/hoon/setup.md+1−1

@@ -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 [Lesson 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](/docs/glossary/noun/) 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+3−3

@@ -36,7 +36,7 @@ Accordingly, the structures produced by the type subexpressions above aren't par

36

37### Type Example Values ('Bunt' Values)

38

39−In other cases, structures _can_ have an effect on runtime semantics. For example, consider the expression `|=(a=@ 15)`. This produces a gate that takes any atom as its sample and returns `15`.

39+In other cases, structures _can_ have an effect on runtime semantics. For example, consider the expression `|=(a=@ 15)`. This produces a [gate](/docs/glossary/gate/) that takes any [atom](/docs/glossary/atom/) as its sample and returns `15`.

40

41The `@` subexpression of `|=(a=@ 15)` produces a structure at compile time. In the compiled program this structure is converted to a default value for the appropriate type, sometimes called an **example** value (or a **bunt** value).

42

@@ -99,7 +99,7 @@ Structures can also become gates at runtime. To produce such a gate, use a type

99>

100```

101

102−In all three cases, the result of evaluation is a gate. For each, the head is a single arm, signified by `1.xxx`. The sample -- i.e., the head of the tail -- in each case is of the type `*`. These gates are sometimes called **molds**.

102+In all three cases, the result of evaluation is a gate. For each, the head is a single [arm](/docs/glossary/arm/), signified by `1.xxx`. The sample -- i.e., the head of the tail -- in each case is of the type `*`. These gates are sometimes called **molds**.

103

104Molds are gates with two special properties: (1) they are guaranteed to produce a value of the type indicated by the type expression, and (2) they are [idempotent](https://en.wikipedia.org/wiki/Idempotence). (A gate `i` is idempotent if and only if the result of applying `i` multiple times to a value produces the same result as applying it once. In other words, `(i val)` must produce the same result as `(i (i val))`.)

105

@@ -143,7 +143,7 @@ Let's review (1) and (2) briefly.

143

144### Basic Types

145

146−The basic types of Hoon are: `*` for nouns, `@` for atoms (possibly with aura information, e.g., `@ud` and `@sx`), `^` for cells, `?` for flags, and `~` for null. You can also make constant, one-value types by using `%` followed by a series of lowercase letters, the hyphen symbol `-`, and numbers. E.g., `%red`, `%2`, `%kebab-case123`. The lone values of these one-value types are sometimes called 'tags'.

146+The basic types of Hoon are: `*` for [nouns](/docs/glossary/noun/), `@` for atoms (possibly with aura information, e.g., `@ud` and `@sx`), `^` for cells, `?` for flags, and `~` for null. You can also make constant, one-value types by using `%` followed by a series of lowercase letters, the hyphen symbol `-`, and numbers. E.g., `%red`, `%2`, `%kebab-case123`. The lone values of these one-value types are sometimes called 'tags'.

147

148Let's illustrate with the irregular `\` \`` cast syntax:

149

tutorials/hoon/style.md+1−1

@@ -44,7 +44,7 @@ These are regular forms -- every rune can be written this way.

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

45forms are regular. All code within a wide form is wide.

46Almost all code has both wide and tall forms, the exception

47−being named cores.

47+being named [cores](/docs/glossary/core/).

48

49The goal of wide/tall forms is to resemble the look of

50procedural code, with its statement/expression distinction,

tutorials/hoon/test-sets.md+4−4

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

6

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

8

9−First 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).

9+First we will cover the essential molds, [arms](/docs/glossary/arm/), 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).

10

11## Running our first test

12

@@ -41,9 +41,9 @@ Here, we ran a generator called `+test` with a path argument `/sys/hoon/set`. Th

41::

42|%

43```

44−We note that the first line that isn't a comment is `/+ *test`, which from [the previous lesson](@/docs/tutorials/hoon/ford.md) you know means that we are importing the shared library `lib/test.hoon`. This is followed by a core which will contain arms that perform our tests, which we will see an example of shortly.

44+We note that the first line that isn't a comment is `/+ *test`, which from [the previous lesson](@/docs/tutorials/hoon/ford.md) you know means that we are importing the shared library `lib/test.hoon`. This is followed by a [core](/docs/glossary/core/) which will contain arms that perform our tests, which we will see an example of shortly.

45

46−In `lib/test.hoon`, we find a core with a few gates: `expect-eq`, `expect-fail`, and `category`. The source for `expect-eq` is:

46+In `lib/test.hoon`, we find a core with a few [gates](/docs/glossary/gate/): `expect-eq`, `expect-fail`, and `category`. The source for `expect-eq` is:

47```hoon

48++ expect-eq

49 |= [expected=vase actual=vase]

@@ -127,7 +127,7 @@ We see that this arm returns a `tang`, i.e. a pretty-printed message, and adds s

127 !> ~

128 !> (~(int in s-nul) s-asc)

129```

130−`%+` is used to call a gate with a cell sample. `expect-eq` is the gate, `!> ~` is the head of the sample, and `!> (~(int in s-nul) s-asc)` is the tail of the sample. `!>` is a rune used to wrap a noun in its type - in other words, it produces a `vase`. We've seen this rune before when we learned about the type spear `-:!>`. Thus, what this block of code is doing is checking whether the expected `vase` that is the product of `!> ~` is equal to the `vase` that is the product of `!> (~(int in s-nul) s-asc)`. `s-nul` is simply the empty set, and here we are taking the intersection of the empty set with `s-asc`, a non-empty set. This ought to produce the empty set of course, and so when this block of code runs, we compare the expected result `!> ~` (which is something we determined by hand) with the actual result `!> (~(int in s-nul) s-asc)`.

130+`%+` is used to call a gate with a cell sample. `expect-eq` is the gate, `!> ~` is the head of the sample, and `!> (~(int in s-nul) s-asc)` is the tail of the sample. `!>` is a rune used to wrap a [noun](/docs/glossary/noun/) in its type - in other words, it produces a `vase`. We've seen this rune before when we learned about the type spear `-:!>`. Thus, what this block of code is doing is checking whether the expected `vase` that is the product of `!> ~` is equal to the `vase` that is the product of `!> (~(int in s-nul) s-asc)`. `s-nul` is simply the empty set, and here we are taking the intersection of the empty set with `s-asc`, a non-empty set. This ought to produce the empty set of course, and so when this block of code runs, we compare the expected result `!> ~` (which is something we determined by hand) with the actual result `!> (~(int in s-nul) s-asc)`.

131```hoon

132 %+ expect-eq

133 !> ~

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

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

9

10## A Start

11

12−For 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.

12+For 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](/docs/glossary/noun/).

13

14In 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

@@ -54,7 +54,7 @@ Let's create a subject with some computations:

5455

55```

56

57−`add` and `mul` are functions of the Hoon standard library. `add` is used to add two atoms, and `mul` is used to multiply them.

57+`add` and `mul` are functions of the Hoon standard library. `add` is used to add two [atoms](/docs/glossary/atom/), and `mul` is used to multiply them.

58

59## Limbs of the Subject

60

@@ -73,7 +73,7 @@ The subject is a noun, just like any other piece of Hoon data. In Lesson 1.2 we

73

74Each fragment of a noun is itself a noun, and hence can be understood as a binary tree as well. Each fragment or 'subtree' sticks out of the original tree, like a **limb**. A 'limb' is a subtree of the subject.

75

76−Sometimes a programmer simply wants to produce a value from the subject. In other cases more is desired -- programmers often want to carry out substantive computations on data in the subject. There are two kinds of limbs to accommodate these two cases: arms and legs.

76+Sometimes a programmer simply wants to produce a value from the subject. In other cases more is desired -- programmers often want to carry out substantive computations on data in the subject. There are two kinds of limbs to accommodate these two cases: [arms](/docs/glossary/arm/) and legs.

77

78**Arms** are limbs of the subject that are used for carrying out substantive computations. We'll talk about arms in the next lesson. **Legs** are limbs that store data. Any limb that isn't an arm is a leg. In this lesson we'll talk about various ways to access legs of the subject.

79

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

@@ -11,7 +11,7 @@ In this lesson we'll cover each.

11

12## Trees

13

14−We use `tree` to make a binary tree data structure in Hoon, e.g., `(tree @)` for a binary tree of atoms.

14+We use `tree` to make a binary tree data structure in Hoon, e.g., `(tree @)` for a binary tree of [atoms](/docs/glossary/atom/).

15

16There are two kinds of `tree` in Hoon: (1) the null tree, `~`, and (2) a non-null tree which is a cell with three parts. Part (i) is the node value, part (ii) is the left child of the node, and part (iii) is the right child of the node. Each child is itself a tree. The node value has the face `n`, the left child has the face `l`, and the right child has the face `r`. The following diagram provides an illustration of a `(tree @)` (without the faces):

17

@@ -32,7 +32,7 @@ Hoon supports trees of any type that can be constructed in Hoon, e.g.: `(tree @)

32{4 8 12 14 16}

33```

34

35−Notice that we don't have to insert the faces manually; by casting the noun above to a `(tree @)` Hoon inserts the faces for us. Let's put this noun in the dojo subject with the face `b` and pull out the tree at the left child of the `12` node:

35+Notice that we don't have to insert the faces manually; by casting the [noun](/docs/glossary/noun/) above to a `(tree @)` Hoon inserts the faces for us. Let's put this noun in the dojo subject with the face `b` and pull out the tree at the left child of the `12` node:

36

37```

38> =b `(tree @)`[12 [8 [4 ~ ~] ~] [14 ~ [16 ~ ~]]]

@@ -88,11 +88,11 @@ $(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.md).

91+Use `set` to create a data structure for a set of values, e.g., `(set @)` for a set of atoms. The `in` [core](/docs/glossary/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.md).

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

95−Two common methods for populating a set include (1) creating it from a list of values using the `sy` function, and (2) inserting items into a set using the `put` arm of the `in` core.

95+Two common methods for populating a set include (1) creating it from a list of values using the `sy` function, and (2) inserting items into a set using the `put` [arm](/docs/glossary/arm/) of the `in` core.

96

97Using `sy`:

98

@@ -138,7 +138,7 @@ Check whether an item is in the set using `has` of `in`:

138%.n

139```

140

141−You can apply a gate to each item of a set using `run` of `in` and produce a new set from the products:

141+You can apply a [gate](/docs/glossary/gate/) to each item of a set using `run` of `in` and produce a new set from the products:

142

143```

144> c

tutorials/hoon/type-checking-and-type-inference.md+4−4

@@ -62,7 +62,7 @@ nest-fail

62

63The `^+` rune takes two subexpressions. The first subexpression is evaluated and its type is inferred. The second subexpression is evaluated and its inferred type is compared against the type of the first. If the type of the second provably nests under the type of the first, the result of the `^+` expression is just the value of its second subexpression. Otherwise, the code fails to compile.

64

65−This rune is useful for casting when you already have a noun -- or expression producing a noun -- whose type you may not know or be able to construct easily. If you want your output value to be of the same type, you can use `^+`.

65+This rune is useful for casting when you already have a [noun](/docs/glossary/noun/) -- or expression producing a [noun](/docs/glossary/noun/) -- whose type you may not know or be able to construct easily. If you want your output value to be of the same type, you can use `^+`.

66

67More examples:

68

@@ -98,7 +98,7 @@ You can evade the `.=` type-check by casting one of its subexpressions to a `*`,

98

99It isn't recommended that you evade the rules in this way, however.

100

101−The `.+` increment rune -- including its `+( )` irregular form -- does a type check to ensure that its subexpression must evaluate to an atom.

101+The `.+` increment rune -- including its `+( )` irregular form -- does a type check to ensure that its subexpression must evaluate to an [atom](/docs/glossary/atom/).

102

103```

104> +(12)

@@ -110,9 +110,9 @@ nest-fail

110

111### Arm Evaluation

112

113−Whenever an arm is evaluated in Hoon it expects to have some version of its parent core as the subject. Specifically, a type check is performed to see whether the arm subject is of the appropriate **type**. We see this in action whenever a gate or a multi-arm door is called.

113+Whenever an [arm](/docs/glossary/arm/) is evaluated in Hoon it expects to have some version of its parent [core](/docs/glossary/core/) as the subject. Specifically, a type check is performed to see whether the [arm](/docs/glossary/arm/) subject is of the appropriate **type**. We see this in action whenever a [gate](/docs/glossary/gate/) or a multi-arm [door](/docs/glossary/door/) is called.

114

115−A gate is a one-armed core with a sample. When it is called, its `$` arm is evaluated with (a version of) the gate as the subject. The only part of the core that might change is the payload, including the sample. Of course, we want the sample to be able to change. The sample is where the argument(s) of the function call are placed. For example, when we call `add` the `$` arm of expects two atoms for the sample, i.e., the two numbers to be added. When the type check occurs, the payload must be of the appropriate type. If it isn't, the result is a `nest-fail` crash.

115+A gate is a one-armed core with a sample. When it is called, its `$` arm is evaluated with (a version of) the gate as the subject. The only part of the core that might change is the [payload](/docs/glossary/payload/), including the sample. Of course, we want the sample to be able to change. The sample is where the argument(s) of the function call are placed. For example, when we call `add` the `$` arm of expects two atoms for the sample, i.e., the two numbers to be added. When the type check occurs, the [payload](/docs/glossary/payload/) must be of the appropriate type. If it isn't, the result is a `nest-fail` crash.

116

117```

118> (add 22 33)

tutorials/hoon/type-polymorphism.md+4−4

@@ -7,7 +7,7 @@ aliases = ["/docs/learn/hoon/hoon-tutorial/type-polymorphism/"]

7

8There 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_%28computer_science%29). ("Polymorphism" = "many forms"; so polymorphic functions accept many forms of data as input.)

9

10−One relatively trivial form of polymorphism involves sub-typing. A gate whose sample is a raw `noun` can accept any Hoon data structure as input -- it's just that the sample will only be treated as a raw noun. For example, consider the `copy` gate below:

10+One relatively trivial form of polymorphism involves sub-typing. A [gate](/docs/glossary/gate/) whose sample is a raw `noun` can accept any Hoon data structure as input -- it's just that the sample will only be treated as a raw [noun](/docs/glossary/noun/). For example, consider the `copy` gate below:

11

12```

13> =copy |=(a=* [a a])

@@ -28,7 +28,7 @@ In this lesson we'll go over Hoon's support for more interesting polymorphic fun

28

29## Polymorphic Properties of Cores

30

31−Hoon supports type polymorphism at the core level. That is, each core has certain polymorphic properties that are tracked and maintained as metadata by Hoon's type system. (See `+$ type` of `hoon.hoon`.) These properties determine the extent to which a core can be used as an interface for values of various types.

31+Hoon supports type polymorphism at the [core](/docs/glossary/core/) level. That is, each core has certain polymorphic properties that are tracked and maintained as metadata by Hoon's type system. (See `+$ type` of `hoon.hoon`.) These properties determine the extent to which a core can be used as an interface for values of various types.

32

33This is rather vaguely put so far. We can clarify by talking more specifically about the kinds of polymorphism supported in Hoon. There are two kinds of type polymorphism for cores: [genericity](https://en.wikipedia.org/wiki/Generic_programming), to include certain kinds of [parametric polymorphism](https://en.wikipedia.org/wiki/Parametric_polymorphism); and [variance polymorphism](https://en.wikipedia.org/wiki/Covariance_and_contravariance_%28computer_science%29), which involves making use of special sub-typing rules for cores.

34

@@ -36,7 +36,7 @@ If you don't understand these very well, that's okay. We'll explain them. Let'

36

37## Dry vs. Wet Cores

38

39−To review briefly, a **core** is a pair of `[battery payload]`. The **battery** contains the various arms of the core (code), and the **payload** contains all the data needed to evaluate those arms correctly (data). Every arm is evaluated with its parent core as the subject. A **gate** (i.e., a Hoon function) is a core with exactly one arm named `$` and with a payload of the form: `[sample context]`. The **sample** is reserved for the function's argument value, and the **context** is any other data needed to evaluate `$` correctly.

39+To review briefly, a **core** is a pair of `[battery payload]`. The **battery** contains the various [arms](/docs/glossary/arm/) of the core (code), and the **payload** contains all the data needed to evaluate those arms correctly (data). Every arm is evaluated with its parent core as the subject. A **gate** (i.e., a Hoon function) is a core with exactly one arm named `$` and with a [payload](/docs/glossary/payload/) of the form: `[sample context]`. The **sample** is reserved for the function's argument value, and the **context** is any other data needed to evaluate `$` correctly.

40

41There are two kinds of cores: **dry** and **wet**. Dry cores, which are more typical, _don't_ make use of **genericity**. Wet cores do. In order to understand generic functions in Hoon, you have to understand the difference between dry and wet cores.

42

@@ -64,7 +64,7 @@ For illustration, consider the gate created by `add`, a function in the Hoon sta

64 sample context

65```

66

67−The `add` code depends on the fact that there are two atoms in the sample: the numbers to be added together. Hence, it is appropriate that only a cell of atoms is permitted for the sample. We can look at the default sample of `add` at address `+6`:

67+The `add` code depends on the fact that there are two [atoms](/docs/glossary/atom/) in the sample: the numbers to be added together. Hence, it is appropriate that only a cell of atoms is permitted for the sample. We can look at the default sample of `add` at address `+6`:

68

69```

70> +6:add

tutorials/hoon/workbook/bomb.md+1−1

@@ -99,7 +99,7 @@ doing here.

99We call `defuse` and pass it `cuts`, the list of tapes we were provided with

100when the generator started.

101

102−Next is the core that has two arms, `defuse` and `rules`. Let's look at `rules`

102+Next is the [core](/docs/glossary/core/) that has two [arms](/docs/glossary/arm/), `defuse` and `rules`. Let's look at `rules`

103quickly.

104

105We can see that it is a `map` of `tape` to `list` of `tape`. For each of the

tutorials/hoon/workbook/digits.md+1−1

@@ -33,7 +33,7 @@ need some "boilerplate" code in the format of `[%say [%noun "data"]]`:

33

34The head of this cell is the literal `%say`.

35

36−In the tail is the gate and its sample: `|= [* [n=@ud ~] ~]`. This is

36+In the tail is the [gate](/docs/glossary/gate/) and its sample: `|= [* [n=@ud ~] ~]`. This is

37where we describe any arguments we are expecting to be passed in when the

38generator is called. We are expecting data of type `@ud`. We give the data the

39face `n` so that we can easily reference it later.

tutorials/hoon/workbook/eightball.md+4−4

@@ -66,10 +66,10 @@ the template that is followed for all `%say` generators.

66`:- %say` creates a cell with `%say` as that cell's head to define

67the generator's format.

68

69−`|= [[* eny=@uv *] *]` is the tail of the cell, a gate, and that gate's first

69+`|= [[* eny=@uv *] *]` is the tail of the cell, a [gate](/docs/glossary/gate/), and that gate's first

70child, a sample. Because the only external data our program is interested in

71using is entropy to seed our random-number generator, that's the only one we

72−will assign a face (`eny`). The `*` elements that you see represent any noun. We

72+will assign a face (`eny`). The `*` elements that you see represent any [noun](/docs/glossary/noun/). We

73use these as fillers: because we don't wish to use the data that's passed to

74those parts of the sample, we don't assign them faces.

75

@@ -135,7 +135,7 @@ elements are the `tape`s that are selected as the 8-Ball's responses.

135

136The code above is our random-number engine.

137

138−`og` is the core in the standard library that contains arms that perform

138+`og` is the [core](/docs/glossary/core/) in the standard library that contains [arms](/docs/glossary/arm/) that perform

139randomness-related operations. `=/ rng ~(. og eny)` passes `eny` to the

140subject of `og`, and then stores the resulting core in a face called `rng`.

141

@@ -149,7 +149,7 @@ store the random result in `val`.

149(snag val answers)

150```

151

152−`snag` is a standard-library arm that that takes two arguments: an atom and

152+`snag` is a standard-library arm that that takes two arguments: an [atom](/docs/glossary/atom/) and

153a `list`. It fetches the element in position `n` of the list, where `n` is the

154value of the atom it was passed. By using the randomized `val` as that position

155argument, we can pull a different response from `answers` every time the

tutorials/hoon/workbook/traffic-light.md+3−3

@@ -47,9 +47,9 @@ relevant to the functionality of our program.

47 --

48```

49

50−`=+` adds a noun to the subject. In our case, the noun in question is the core

50+`=+` adds a [noun](/docs/glossary/noun/) to the subject. In our case, the [noun](/docs/glossary/noun/) in question is the [core](/docs/glossary/core/)

51that is opened with `|%` and closed with `--`. This core is used to store types,

52−and does that with the arm that it contains.

52+and does that with the [arm](/docs/glossary/arm/) that it contains.

53

54`++ state` creates an arm called `state`, which will be used as the name of the

55new type that is created in the code that follows, `?(%red %yellow %green)`.

@@ -89,7 +89,7 @@ With `|%`, we are finally at the meat of the program. This core that we just

89named has two arms: `look`, which gives us the current state, defined later; and

90`set`, which gives us a simple way to modify the value of `current-state`.

91

92−The gate we are producing with `|=` may look a bit strange, so let's break it

92+The [gate](/docs/glossary/gate/) we are producing with `|=` may look a bit strange, so let's break it

93down.

94

95`s=state` allows for an argument of type `state` and gives it a face `s`.

tutorials/nock/definition.md+1−1

@@ -6,7 +6,7 @@ aliases = ["docs/learn/nock/definition/"]

6+++

7

8Nock is a Turing-complete function that maps a cell

9−`[subject formula]` to a noun `product`, where `subject` is the

9+`[subject formula]` to a [noun](/docs/glossary/noun/) `product`, where `subject` is the

10data, `formula` is the code, and `product` is the result.

11

12To program in Hoon, this is all you need to know about Nock.