2title = "1.5 Gates (Hoon Functions)"
5aliases = ["/docs/learn/hoon/hoon-tutorial/gates/"]
7In this lesson you're going to learn about Hoon functions.
11The 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. What the return value is 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`).
13That output value depends solely upon input value(s) is an important property of functions. This property is called [referential transparency](https://en.wikipedia.org/wiki/Referential_transparency), and we make use of it throughout the Urbit software stack.
15Functions 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.
17You've already used two functions from the Hoon standard library: `add` and `mul`. These are implemented with gates, and you call them from the dojo in the following way:
29A core is a cell: `[battery payload]`.
31A 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.
34Gate: [$ [Sample Context]]
37As a tree, a gate looks like the following:
47Like 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.
49## Creating Your First Gate
51Let'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':
54> =inc |=(a=@ (add 1 a))
66The gate works as promised -- it takes any number `n` and returns `n + 1`. Let's take a closer look at what the `|=` is doing.
70We 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).
72In 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.
74In `inc`, the product is defined by `(add 1 a)`. There's not much to it -- it returns the value of `a + 1`!
76The second subexpression after the `|=` rune is used to build the gate's `$` arm. That's where all the computations go.
80A 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.
86 {our/@p now/@da eny/@uvJ}
87 <19.anu 24.tmo 6.ipz 38.ard 119.spd 241.plj 51.zox 93.pqh 74.dbd 1.qct $141>
94The arm of a gate encodes the instructions for the Hoon function in question.
96The pretty printer represents the `$` arm of `inc` as `1.jgn`. To see the actual noun of the `$` arm, enter `+2:inc` into the dojo:
100[8 [9 8 0 4.095] 9 2 [0 4] [[7 [0 3] 1 1] 0 14] 0 11]
103This is un-computed Nock. You don't need to understand any of this.
105It's worth pointing out that the arm name, `$`, can be used like any other name. We can compute `$` directly with `$:inc` in the dojo:
112This 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.
116The 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`.
118Let's look at the gate for `inc` again, paying particular attention to its sample:
124 {our/@p now/@da eny/@uvJ}
125 <19.anu 24.tmo 6.ipz 38.ard 119.spd 241.plj 51.zox 93.pqh 74.dbd 1.qct $141>
130We 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:
137We 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`:
144The placeholder value is sometimes called a **bunt** value. The bunt value is determined by the input type; for atoms, `@`, the bunt value is `0`.
146The 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)`.
150The context of a gate contains other data that may be necessary for the `$` arm to evaluate correctly. The context always located at the tail of the tail of the gate, i.e., `+7` of the gate. There is no requirement that the context have any particular arrangement, though often it does.
152Let's look at the context of `inc`:
157 now=~2018.12.12..18.55.06..df2b
159 \/0v2g0.cmm6d.1igpo.llg7o.4921d.nov38.vjsgp.mdfln.8pt9f.n23hj.qc6q9.8p7bd\/
160 .2eo59.qko43.1jgd2.rtc44.egooe.esvft.orohc.i9ufn.4rnur
163 <19.anu 24.tmo 6.ipz 38.ard 119.spd 241.plj 51.zox 93.pqh 74.dbd 1.qct $141>
167This 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.
171Write 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.
173## Gates Define Functions of the Sample
175The 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.
177In Hoon one can use `(gate arg)` syntax to make a function call. For example,
184The 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.
186Remember 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`.
188Notice 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.
190Let's unbind `inc` to keep the subject tidy:
199### Modifying the Context of a Gate
201It _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`:
210Now let's write a gate called `ten` that adds `b` to the input value:
213> =ten |=(a=@ (add a b))
225We can unbind `b` from the dojo subject, and `ten` works just as well because it's using a copy of `b` stored its context:
240We 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:
253Before finishing the lesson let's unbind `ten`:
259## Exercise 1.5a Solution
261Write 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.
264> =double |=(a=@ (mul 2 a))
273### [Next Up: Walkthrough -- Recursion](../recursion)
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