@@ -1,10 +1,10 @@
11+++
2−title = "Intro to Gall"
3−weight = 0
2+title = "2.7.1 Walkthrough: Egg Timer"
3+weight = 36
44template = "doc.html"
55+++
66
7−Arvo is divided up into parts called vanes. Gall is one of those vanes and it is the one responsible for providing an api for building stateful applications in Urbit. Gall is a complex system that takes a lot of getting used to so let's dip our toes in with a very simple app.
7+The Arvo operating system is divided up into modules called vanes. Gall is the vane responsible for providing an API for building stateful applications in Urbit. Gall is a complex system that takes a lot of getting used to, so let's dip our toes in with a simple egg-timer app.
88
99
1010```
@@ -26,7 +26,7 @@ Arvo is divided up into parts called vanes. Gall is one of those vanes and it is
2626--
2727```
2828
29−The first thing to notice is that we are creating a `core` and a `door`. This is a typical style of gall programming where your types are defined in the first `core` and your application is defined in the following `door`.
29+The first thing to notice is that we are creating a `core` (`|%`) and a `door` (`|_`). This is a typical style of Gall programming where your types are defined in the first `core` and your application is defined in the following `door`.
3030
3131```
3232|%
@@ -35,15 +35,17 @@ The first thing to notice is that we are creating a `core` and a `door`. This is
3535--
3636```
3737
38−The `core` here defines two types `effect` and `syscall`. An `effect` is a `pair` of `bone` and `syscall`. A `bone` is an opaque reference to a set of events. A `syscall` is a request to Arvo to do something for us. In this case the only valid `syscall` will be `%wait` which we'll discuss in a bit. It's important to note that the names `effect` and `syscall` are not important and you can call them whatever you would like. Commonly you will see them called `move` and `card` respectively but we've changed the names here to try to help provide some clarity over the older convention.
38+The `core` here defines two types: `effect` and `syscall`. An `effect` is a `pair` of `bone` and `syscall`. A `bone` is a Gall-only type that identifies app event chains by mapping atoms to them. We define `syscall` to be a request to Arvo to do something for us. In this case, the only valid `syscall` will be `%wait` which we'll discuss in a bit.
3939
40−The sample of the `door` is
40+It's important to note that the names `effect` and `syscall` are arbitrary; you can call them whatever you'd like. Commonly you will see them called `move` and `card`, respectively, but we've changed the names here to try to introduce some clarity that that older convention lacks.
41+
42+The sample of the `door` is:
4143
4244```
4345[bowl:gall ~]
4446```
4547
46−You can find the full definition of `bowl` in `sys/zuse.hoon` but for now it's enough to know that this is the default app state and includes various faces for information. You can see a short list of some of them below.
48+You can find the full definition of `bowl` in `sys/zuse.hoon`, but for now it's enough to know that this is the default app state and includes various faces for information. Below are some important such faces:
4749
4850`our` The current ship
4951`src` The ship the request originated with
@@ -51,8 +53,7 @@ You can find the full definition of `bowl` in `sys/zuse.hoon` but for now it's e
5153`eny` Entropy
5254`now` The current time of the event
5355
54−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
55−
56+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:
5657
5758```
5859++ poke-noun
@@ -62,42 +63,39 @@ The `door` we've made has two arms `poke-noun` and `wake`. Gall is capable of di
6263 [ost %wait /(scot %da now) (add now t)]
6364```
6465
65−We're going to create a gate that takes a single `@dr` argument. `@dr` is an aura for a 128-bit relative date. Here are a few examples.
66−
66+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.
6767
68−```
69−~s17 (17 seconds)
70−~m20 (20 minutes)
71−~d42 (42 days)
72−```
68+`~s17` 17 seconds
69+`~m20` 20 minutes
70+`~d42` 42 days
7371
74−As a mater 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 cast by example. Our example is a cell of `list` of `effect`, which we `bunt` with `*`, and `+>.$`, the enclosing core which is our `door`.
72+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 `effect`, which we `bunt` with `*`, is the head; `+>.$`, the enclosing core which is our `door`, is the tail.
7573
76−Next 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
74+Next 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:
7775
7876```
7977[[[ost %wait /(scot %da now) (add now t)] ~] +>.$]
8078```
8179
82−but we want to follow the principle of heaviest twigs to the bottom. `ost` is the `bone`, opaque reference to a chain of events, that we already have contained in the `bowl` so we're just going to continue to use it here. `%wait` is the name of the `syscall`, in this case a request to the behn vain to start a timer for us.
80+`ost` is the `bone`, the opaque reference to a chain of events, that comes from `bowl`, so we're going to continue to use it here. `%wait` is the name of the `syscall`, in this case a request to the Behn vain to start a timer for us.
8381
84−After `%wait` we have the `path`, a `list` of `cords` that serves as the unique identifier for this `syscall`
82+After `%wait`, we have the `path`, a `list` of `cords` that serves as the unique identifier for this `syscall`:
8583
8684```
8785/(scot %da now)
8886```
8987
90−The `/` here is an irregular syntax to make a `path` and `scot` is going to transform `now`, the current time as given to us in the `bowl` from a `@da` to a `cord`.
88+The `/` here is an irregular syntax to make a `path`, and `scot` is going to transform `now`, the current time as given to us by `bowl`, from a `@da` to a `cord`.
9189
92−The final part of this `syscall` is
90+The final part of this `syscall` is:
9391
9492```
9593(add now t)
9694```
9795
98−`now` is again the current time as a `@da` and `t` was our `@dr`. Through the magic of mathematics, we can add these two to get a `@da` that is `t` time in the future from now.
96+`now` is the current time of type `@da`, and `t` was declared as `@dr`. Because they are both atoms, we can add `now` and `t` these two to get an atom that is `t` units of time into the future from `now`. That produced atom can be interpreted as a `@da`.
9997
100−That's all for our `poke-noun` arm. What about when the timer goes off? `behn` will create a `move` similar to how we created one only this time it will end up being dispatched back to us in the `++wake` arm.
98+That's all for our `poke-noun` arm. But what about when the timer goes off? Behn will create a `move` similar to how we created one with `effect`, only this time it will end up being dispatched back to us in the `++wake` arm. Behn always looks for an arm named `++wake` when a timer goes off; it is defined this way in the vane's code. So any So any app that wants to use a timer trigger needs to have an arm called `++wake`.
10199
102100```
103101++ wake
@@ -107,14 +105,16 @@ That's all for our `poke-noun` arm. What about when the timer goes off? `behn` w
107105 [~ +>.$]
108106```
109107
110−`wake` is a `gate` that has two arguments, a `wire` and a `(unit tang)` with the face `error`. The syntax used here `=wire` is a shortcut for `wire=wire`. A `wire` is a specialized kind of `path`. This will be the `path` we gave in our original `syscall` so that we can use to dispatch on if we wanted to do different things based on which event this is. In this case, we don't.
108+`wake` is a `gate` that has two arguments: a `wire`, and a `(unit tang)` with the face `error`. The syntax of `=wire` is a shortcut for `wire=wire`; it's a common pattern to shadow the name of a type when you only have one instance of the type and are not going to refer to the type itself. A `wire` is just an alias for `path`. Our `wire` will be the `path` that we gave original `syscall`. If we needed to do something based on which request caused this gate to be called, we could use the wire to do so. In this case, we don't do perform such a dispatch.
111109
112−Next we have the same cast we used in `++poke-noun` to make sure we are producing the correct thing for gall. These casts are not strictly speaking necessary as the type system can infer what the type will be but they can be very useful both for debugging our own code and for someone coming behind us trying to determine what our code should be producing.
110+Next we have the same cast we used in `++poke-noun` to make sure we are producing the correct thing for Gall. These casts are not strictly necessary, as the type system can infer what the type will be, but they can be very useful both for debugging our own code and for someone else trying to determine what our code should be producing.
113111
114112```
115113~& "Timer went off!"
116114```
117115
118−`~&` is the debugging printf rune. Here we're simply going to output a message. We could however do any other computation here we wanted to happen when `++wait` gets called.
116+`~&` is the debugging printf rune. Here we're using it to output a message. We could, however, modify this line of code to do any other computation we would want to happen when `++wait` gets called.
117+
118+Finally, we need to produce our `effect`. Here the effect is simply `[~ +>.$]`, since we have no `syscall` to make and we are not changing the state of our app. We just use the `door` without changing its sample.
119119
120−Finally we need to produce our `effect`, which here is simply `[~ +>.$]` since we have no `syscall` or `cards` we want to make and we are not changing the state of our app, we just use the `door` without changing it's sample.
120+### [Next Up: Reading -- Ford](../ford)