2title = "1.4 Gates (Hoon Functions)"
5aliases = ["/docs/learn/hoon/hoon-tutorial/gates/"]
8In this lesson you're going to learn about Hoon functions.
12The word "function" is used in various ways, but let's start by talking about them in the [mathematical sense](https://en.wikipedia.org/wiki/Function_%28mathematics%29). Roughly put, a function takes one or more arguments (i.e., input values) and returns a value. The return value depends solely on the argument(s), and nothing else. For example, we can understand multiplication as a function: it takes two numbers and returns another number. It doesn't matter where you ask, when you ask, or what kind of hat you're wearing when you ask. If you pass the same two numbers (e.g., `3` and `4`), you get the same answer returned every time (`12`).
14That 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.
16Functions 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.
18You'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:
30A core is a cell: `[battery payload]`.
32A 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.
35Gate: [$ [Sample Context]]
38As a tree, a gate looks like the following:
48Like all arms, `$` is computed with its parent core as the subject. When `$` is computed, the resulting value is called the "product" of the gate. No other data is used to calculate the product other than the data in the gate itself.
50## Creating Your First Gate
52Let'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":
55> =inc |=(a=@ (add 1 a))
67The gate works as promised -- it takes any number `n` and returns `n+1`. Let's take a closer look at what the `|=` is doing.
71We typically use the `|=` rune to create a gate. In the expression above the `|=` is immediately followed by a set of parentheses containing two subexpressions: `a=@` and `(add 1 a)`. The first defines the gate's sample (input value type), and the second defines the gate's product (value).
73In the example gate above, `inc`, the sample is defined by `a=@`. This means that the sample is defined as an atom, `@`, meaning that the gate will take as input anything of that type. The sample is given the face `a`. With the face it's easier to refer to the sample in later code, if desired.
75In `inc`, the product is defined by `(add 1 a)`. There's not much to it -- it returns the value of `a+1`!
77The second subexpression after the `|=` rune is used to build the gate's `$` arm. That's where all the computations go.
81A gate is a one-armed core with a sample: `[$ [Sample Context]]`. Let's go over these parts a little more carefully, using `inc` as our example.
87 {our/@p now/@da eny/@uvJ}
88 <19.anu 24.tmo 6.ipz 38.ard 119.spd 241.plj 51.zox 93.pqh 74.dbd 1.qct $141>
95The arm of a gate encodes the instructions for the Hoon function in question.
97The 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:
101[8 [9 8 0 4.095] 9 2 [0 4] [[7 [0 3] 1 1] 0 14] 0 11]
104This is un-computed Nock. You don't need to understand any of this.
106It's worth pointing out that the arm name, `$`, can be used like any other name. We can compute `$` directly with `$:inc` in the Dojo:
113This result may seem a bit strange. We didn't call `inc` or in any other way pass it a number. Yet using `$` to evaluate `inc`'s arm seems to work -- sort of, anyway. Why is it giving us `1` as the return value? We can answer this question after we understand gate samples a little better.
117The sample of a gate is the address reserved for storing the argument(s) to the Hoon function. The sample is always at the head of the gate's tail, i.e., `+6`.
119Let's look at the gate for `inc` again, paying particular attention to its sample:
125 {our/@p now/@da eny/@uvJ}
126 <19.anu 24.tmo 6.ipz 38.ard 119.spd 241.plj 51.zox 93.pqh 74.dbd 1.qct $141>
131We see `a/@`. This may not be totally clear, but it should make _some_ sense. This is the pretty-printer's way of indicating an atom with the face `a`. Let's take a closer look:
138We see now that the sample of `inc` is the value `0`, and has `a` as a face. This is a placeholder value for the function argument. If you evaluate the `$` arm of `inc` without passing it an argument the placeholder value is used for the computation, and the return value will thus be `0+1`:
145The placeholder value is sometimes called a **bunt** value. The bunt value is determined by the input type; for atoms, `@`, the bunt value is `0`.
147The face value of `a` comes from the way we defined the gate above: `|=(a=@ (add 1 a))`. It was so we could use `a` to refer to the sample to generate the product with `(add 1 a)`.
151The context of a gate contains other data that may be necessary for the `$` arm to evaluate correctly. The context is always located at the tail of the tail of the gate, i.e., `+7` of the gate. There is no requirement for the context to have any particular arrangement, though often it does.
153Let's look at the context of `inc`:
158 now=~2018.12.12..18.55.06..df2b
160 \/0v2g0.cmm6d.1igpo.llg7o.4921d.nov38.vjsgp.mdfln.8pt9f.n23hj.qc6q9.8p7bd\/
161 .2eo59.qko43.1jgd2.rtc44.egooe.esvft.orohc.i9ufn.4rnur
164 <19.anu 24.tmo 6.ipz 38.ard 119.spd 241.plj 51.zox 93.pqh 74.dbd 1.qct $141>
168This is exactly the default Dojo subject, from before we put `inc` into the subject. The `|=` expression defines the context as whatever the subject is. This guarantees that the context has all the information it needs to have for the `$` arm to work correctly.
172Write a gate that takes an atom, `a=@`, and which returns double the value of `a`. Bind this gate to `double` and test it in the Dojo. A solution is given at the end of this lesson.
174## Gates Define Functions of the Sample
176The value of a function's output depends solely upon the input value. This is one of the features that make functions desirable in many programming contexts. It's worth going over how Hoon function calls implement this feature.
178In Hoon, one can use `(gate arg)` syntax to make a function call. For example:
185The name of the gate is `inc`. How is the `$` arm of `inc` evaluated? When a function call occurs, a copy of the `inc` gate is created, but with one modification; the sample is replaced with the function argument. Then the `$` arm is computed against this modified version of the `inc` gate.
187Remember that the default or "bunt" value of the sample of `inc` is `0`. In the function call above, a copy of the `inc` gate is made but with a sample value of `234`. When `$` is computed against this modified core, the product is `235`.
189Notice that neither the arm nor the context is modified before the arm is evaluated. That means that the only part of the gate that changes before the arm evaluation is the sample. Hence, we may understand each gate as defining a function whose argument is the sample. If you call a gate with the same sample, you'll get the same value returned to you every time.
191Let's unbind `inc` to keep the subject tidy:
200### Modifying the Context of a Gate
202It _is_ possible to modify the context of a gate when you make a function call; or, to be more precise, it's possible to call a mutant copy of the gate in which the context is modified. To illustrate this let's use another example gate. Let's write a gate which uses a value from the context to generate the product. Bind `b` to the value `10`:
211Now let's write a gate called `ten` that adds `b` to the input value:
214> =ten |=(a=@ (add a b))
226We can unbind `b` from the Dojo subject, and `ten` works just as well because it's using a copy of `b` stored its context:
241We can use `ten(b 25)` to produce a variant of `ten`. Calling this mutant version of `ten` causes a different value to be returned than we'd get with a normal `ten` call:
254Before finishing the lesson let's unbind `ten`:
260## Exercise 1.4.1a: Answer
262Write a gate that takes an atom, `a=@`, and which returns double the value of `a`. Bind this gate to `double` and test it in the Dojo.
265> =double |=(a=@ (mul 2 a))
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list