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

git.iko.soy/urbit.org

Linked first instance of hoon glossary entries (#789)

* Linked first instance of hoon glossary entries * fixed plurals * plural fix

commit09325aec7ffa6bd9980a77827e62ffad71e5424c authorDavid Kerschner <david@tlon.io> dateWed 29 Jan 2020, 16:15 (7 years ago) parente829821

46 files changed+139−139

compare with master

unifiedsplit

tutorials/arvo/ames.md+5−5

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

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

8989

9090The `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

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

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

9494massive unless you're willing to wait.

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

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

105105```

106106

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

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

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

110110if 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

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

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

115115neighbor 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

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

118118The code predates the widespread usage of that name.

119119

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

162162into the meal.

163163

164164Finally, 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

166166acknowledged messages, we use `%bund`.

167167

168168```hoon

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

204204```

205205

206206For 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.

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

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

210210actual 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

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

7777```

7878

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_:

8080

8181```

8282L: History -> State.

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

120120

121121### Event log

122122

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.

124124

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

126126lead 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

247247

248248## Overall structure

249249

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:

251251 + Types

252252 + Section 3bE Arvo Core

253253 + Implementation core

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

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

476476expected to happen in an imperative setting.

477477

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

479479follows.

480480

481481```hoon

tutorials/arvo/clay.md+4−4

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

2424## Architecture

2525

2626Clay 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

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

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

3030arvo 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

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

208208from the text ones.

209209

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`,

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

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

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

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

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

923923

924924`%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

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

927927moment, and may in fact be unimplemented.

928928

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

24422442 ==

24432443```

24442444

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.

24462446

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

24482448sense at all.

tutorials/arvo/eyre.md+4−4

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

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

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

5959in `++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

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

6262

6363XX 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?

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

9696

9797Now, 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`

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

100100on.

101101

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

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

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

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

413413

414414## 3. Requests

415415

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

538538

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

540540

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.

542542

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

544544

tutorials/arvo/ford.md+3−3

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

9393

9494### `%reef`

9595

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

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

9898

9999### `%ride`

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

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

403403

404404Filtered `/_` 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

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

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

408408contents of that file.

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

420420

421421### `/;` "fasmic"

422422

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

424424with the result of the horn as its sample.

425425

426426Example:

tutorials/arvo/gall.md+2−2

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

6161

6262## Specification

6363

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

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

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

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

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

361361### Vases and cages

362362

363363A `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

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

366366vase has three operations:

367367

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

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

123123can upgrade Hoon over the network without downtime.

124124

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

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

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

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

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

128128

129129### 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

1212

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

1414

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.

1616

1717Chapter 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/"]

88The 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.

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)

1111

1212``` hoon

1313|= [m=@ n=@]

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

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

44template = "doc.html"

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

66+++

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

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

1010

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

1414

1515An **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.

1616

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.

1818

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.

2020

2121## Your First Core

2222

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

110110

111111Note: 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.

112112

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.

114114

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

116116

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

158158--

159159```

160160

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

162162

163163```hoon

164164++ handle-poke

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

212212

213213Continuing 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.

214214

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/"]

66+++

77Like 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.

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.

1010

1111Type 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**.

1212

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

525215

5353```

5454

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

5656

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

5858

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

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

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

66+++

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.

1010```hoon

1111:- %say

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

3838:- %noun

3939```

4040

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.

4242

4343```hoon

4444=< =~ new-account

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

5151

5252In 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.

5353

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.

5555

5656```hoon

5757|%

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

6767--

6868```

6969

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

7171

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

7373

tutorials/hoon/behn.md+1−1

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

2020

2121## Behn

2222

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

2424

2525Behn 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.

2626

tutorials/hoon/caesar.md+6−6

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

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

123123event of an error.

124124

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

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

127127as 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/)

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

130130

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

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

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

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

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](/docs/glossary/arm/) before they are defined. Without

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

136136

137137```hoon

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

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

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

211211

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

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

214214

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

216216the program crashes.

217217

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

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

219219

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

221221the 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

1818==

1919```

2020

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.

2222

2323```hoon

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

2525```

2626

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

2828

2929```hoon

3030:- %noun

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

8585

8686- `?!` ("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.

8787

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

8989

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

9191

tutorials/hoon/doors.md+4−4

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

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

66+++

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.

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

1111

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

210210

211211## Doors

212212

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.

214214

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

216216

217217```

218218 Door

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

250250

251251#### Back to the Example

252252

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

254254

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

256256

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

5454- `eny` Guaranteed-fresh entropy

5555- `now` The current time

5656

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:

5858

5959```hoon

6060++ poke-noun

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

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

6565```

6666

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.

6868

6969- `~s17` 17 seconds

7070- `~m20` 20 minutes

7171- `~d42` 42 days

7272

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.

7474

7575Next 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:

7676

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

2121==

2222```

2323

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.

2525

2626```hoon

2727%- flop

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

5858==

5959```

6060

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

9191

9292## Using Ford

9393

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

9595

9696### Data types

9797

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

113113

114114Some examples of subtypes include:

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

116− - `%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`.

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](/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`.

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

119119

120120 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

1010## bowl and moves

1111

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.

1313

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.

1515

1616A `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.

1717

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

2626 ==

2727```

2828

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.

3030

3131## Arms

3232

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

3434

3535### ++prep

3636

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.

3838

3939Often 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.

4040

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

1212

1313That 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.

1414

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.

1616

1717You'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:

1818

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

2828

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

3030

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.

3232

3333```

3434Gate: [$ [Sample Context]]

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

4848

4949## Creating Your First Gate

5050

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':

5252

5353```

5454> =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

9393

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

9595

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:

9797

9898```

9999> +2:inc

tutorials/hoon/generators.md+6−6

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

1616### Naked Generators

1717

1818A 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

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

2121very simple one:

2222

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

4949

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

5151for 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

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

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

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

141141(add 40 2)

142142```

143143

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

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

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

147147`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

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

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

232232

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

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

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](/docs/glossary/core/) with the subject of `eny`. Recall that `eny` is our entropy

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

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

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

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

601601

602602## Conclusion

603603

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

5757

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

5959

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.

6161

6262### Noun Literals

6363

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.

6565

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

6767

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

124124- `add`

125125- `mul`

126126

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

128128

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

130130

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

254254%.y

255255```

256256

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.

258258

259259```

260260> %+ add 11 11

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

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

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

66+++

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.

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

1111

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.

1313

1414```hoon

1515++ fold

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

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

2222```

2323

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.

2525

2626```hoon

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

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

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

220220

221221### Default Code Components

222222

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.

224224

225225As 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.

226226

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

257257 ==

258258```

259259

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.

261261

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

263263

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

265265

266266`++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.

267267

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

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

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

66+++

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.

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

1111

1212```hoon

1313=< (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

5757--

5858```

5959

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

6161

6262

6363```hoon

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

6868 ~

6969```

7070

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.

7272

7373`$_` 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.

7474

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

7676

7777The 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.

7878

tutorials/hoon/libraries.md+3−3

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

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

66+++

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.

1010```hoon

1111|%

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

6262

6363On 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.

6464

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.

6666

6767

6868```hoon

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

9191 ==

9292```

9393

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

9595

9696The `?+` 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.

9797

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

4444

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

4646

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.

4848

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.

5050

5151Our 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.

5252

tutorials/hoon/lists.md+3−3

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

88# Lists

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

1111

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

1313

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

1515

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.

1717

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

1919

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

119119

120120#### `flop` Exercise 1.5a

121121

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.

123123

124124### `sort`

125125

tutorials/hoon/molds.md+2−2

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

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

66+++

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.

1010Let'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.

1111

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

3232 |$ [item]

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

3434```

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.

3636

3737

3838```hoon

tutorials/hoon/nouns.md+2−2

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

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

66+++

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.

1010## Noun Definition

1111

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.

1313

1414Here are some atoms:

1515

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

3737

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

3939`(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/)

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

4242

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

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

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

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

140140`@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

142142point.

143143

144144We 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.

175175#### A Note on `$`

176176

177177`$` (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

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

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

181181will 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:

626217

6363```

6464

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.

6666

6767## Generators

6868

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

3636

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

3838

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

4040

4141The `@` 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).

4242

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

9999>

100100```

101101

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

103103

104104Molds 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))`.)

105105

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

143143

144144### Basic Types

145145

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

147147

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

149149

tutorials/hoon/style.md+1−1

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

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

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

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

47−being named cores.

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

4848

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

5050procedural code, with its statement/expression distinction,

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

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

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

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

1010

1111## Running our first test

1212

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

4141::

4242|%

4343```

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.

4545

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:

4747```hoon

4848++ expect-eq

4949 |= [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

127127 !> ~

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

129129```

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

131131```hoon

132132 %+ expect-eq

133133 !> ~

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

1010## A Start

1111

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

1313

1414In 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:

1515

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

545455

5555```

5656

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.

5858

5959## Limbs of the Subject

6060

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

7373

7474Each 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.

7575

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.

7777

7878**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.

7979

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

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

1111

1212## Trees

1313

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

1515

1616There 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):

1717

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

3232{4 8 12 14 16}

3333```

3434

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:

3636

3737```

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

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

8888

8989## Sets

9090

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

9292

9393As 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.

9494

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.

9696

9797Using `sy`:

9898

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

138138%.n

139139```

140140

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:

142142

143143```

144144> c

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

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

6262

6363The `^+` 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.

6464

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 `^+`.

6666

6767More examples:

6868

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

9898

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

100100

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

102102

103103```

104104> +(12)

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

110110

111111### Arm Evaluation

112112

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.

114114

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.

116116

117117```

118118> (add 22 33)

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

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

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

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:

1111

1212```

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

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

2828

2929## Polymorphic Properties of Cores

3030

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.

3232

3333This 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.

3434

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

3636

3737## Dry vs. Wet Cores

3838

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.

4040

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

4242

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

6464 sample context

6565```

6666

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`:

6868

6969```

7070> +6:add

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

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

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

100100when the generator started.

101101

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`

103103quickly.

104104

105105We 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"]]`:

3333

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

3535

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

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

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

3939face `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.

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

6767the generator's format.

6868

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

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

7171using 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

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

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

7575

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

135135

136136The code above is our random-number engine.

137137

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

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

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

141141

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

149149(snag val answers)

150150```

151151

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

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

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

155155argument, 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.

4747 --

4848```

4949

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

5151that 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.

5353

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

5555new 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

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

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

9191

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

9393down.

9494

9595`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/"]

66+++

88Nock 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

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

1111

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