<commit_before>+++
title = "1.8 Doors"
weight = 16
template = "doc.html"
aliases = ["/docs/learn/hoon/hoon-tutorial/doors/"]
+++

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.

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

## Two Kinds of Function Calls

There are two ways of making a function call in Hoon.  First, you can call a gate in the subject by name.  This is what you did with `inc` in the last lesson; you bound `inc` to a gate that adds `1` to an input:

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

> (inc 10)
11

> =inc
```

The second way of making a function call involves an expression that _produces_ a gate:

```
> (|=(a=@ (add 1 a)) 123)
124

> (|=(a=@ (mul 2 a)) 123)
246
```

The difference is that `inc` is an already-created gate in the subject when we called it.  The latter calls involve producing a gate that doesn't exist anywhere in the subject, and then calling it.

Are calls to `add` and `mul` of the Hoon standard library of the first kind, or the second?

```
> (add 12 23)
35

> (mul 12 23)
276
```

They're of the second kind.  Neither `add` nor `mul` resolves to a gate directly; they're each arms that _produce_ gates.

Often the difference doesn't matter much.  Either way you can do a function call using the `(gate arg)` syntax.

It's important to learn the difference, however, because for certain use cases you'll want the extra flexibility that comes with having an already produced core in the subject.

## A Gate-Building Core

Let's make a core with arms that build gates of various kinds.  As we did in a previous lesson, we'll use the `|%` rune.  Feel free to cut and paste the following into the dojo:

```hoon
> =c |%
  ++  inc  |=(a=@ (add 1 a))
  ++  add-two  |=(a=@ (inc (inc a)))
  ++  double  |=(a=@ (mul 2 a))
  ++  triple  |=(a=@ (mul 3 a))
  --
```

Let's try out these arms, using them for function calls:

```
> (inc:c 10)
11

> (add-two:c 10)
12

> (double:c 10)
20

> (triple:c 10)
30
```

Notice that each arm in core `c` is able to call the other arms of `c` -- `add-two` uses the `inc` arm to increment a number twice.  As a reminder, each arm is evaluated with is parent core as the subject.  In the case of `add-two` the parent core is `c`, which has `inc` in it.

### Mutating a Gate

Let's say you want to modify the default sample of the gate for `double`.  We can infer the default sample by calling `double` with no argument:

```
> (double:c)
0
```

Given that `a x 2 = 0`, `a` must be `0`.  (Remember that `a` is the face for the `double` sample, as defined in the core we bound to `c` above.)<commit_msg>Fix typo in doors.md<commit_after>+++
title = "1.8 Doors"
weight = 16
template = "doc.html"
aliases = ["/docs/learn/hoon/hoon-tutorial/doors/"]
+++

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.

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

## Two Kinds of Function Calls

There are two ways of making a function call in Hoon.  First, you can call a gate in the subject by name.  This is what you did with `inc` in the last lesson; you bound `inc` to a gate that adds `1` to an input:

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

> (inc 10)
11

> =inc
```

The second way of making a function call involves an expression that _produces_ a gate:

```
> (|=(a=@ (add 1 a)) 123)
124

> (|=(a=@ (mul 2 a)) 123)
246
```

The difference is that `inc` is an already-created gate in the subject when we called it.  The latter calls involve producing a gate that doesn't exist anywhere in the subject, and then calling it.

Are calls to `add` and `mul` of the Hoon standard library of the first kind, or the second?

```
> (add 12 23)
35

> (mul 12 23)
276
```

They're of the second kind.  Neither `add` nor `mul` resolves to a gate directly; they're each arms that _produce_ gates.

Often the difference doesn't matter much.  Either way you can do a function call using the `(gate arg)` syntax.

It's important to learn the difference, however, because for certain use cases you'll want the extra flexibility that comes with having an already produced core in the subject.

## A Gate-Building Core

Let's make a core with arms that build gates of various kinds.  As we did in a previous lesson, we'll use the `|%` rune.  Feel free to cut and paste the following into the dojo:

```hoon
> =c |%
  ++  inc  |=(a=@ (add 1 a))
  ++  add-two  |=(a=@ (inc (inc a)))
  ++  double  |=(a=@ (mul 2 a))
  ++  triple  |=(a=@ (mul 3 a))
  --
```

Let's try out these arms, using them for function calls:

```
> (inc:c 10)
11

> (add-two:c 10)
12

> (double:c 10)
20

> (triple:c 10)
30
```

Notice that each arm in core `c` is able to call the other arms of `c` -- `add-two` uses the `inc` arm to increment a number twice.  As a reminder, each arm is evaluated with its parent core as the subject.  In the case of `add-two` the parent core is `c`, which has `inc` in it.

### Mutating a Gate

Let's say you want to modify the default sample of the gate for `double`.  We can infer the default sample by calling `double` with no argument:

```
> (double:c)
0
```

Given that `a x 2 = 0`, `a` must be `0`.  (Remember that `a` is the face for the `double` sample, as defined in the core we bound to `c` above.)
{'fraction_non_alphanumeric': 0.11305678340700442, 'fraction_numerical': 0.020401224073444406, 'mean_word_length': 3.5640031031807604, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 29, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6239515', 'n_tokens_mistral': 2049, 'n_tokens_neox': 1886, 'n_words': 980}