@@ -13,20 +13,21 @@ take - a `%poke-ack`.
1313
1414Whenever something tries to poke your agent, Gall calls your agent's `on-poke`
1515arm and give it the `cage` from the poke as its sample. The `on-poke` arm will
16−contain a gate that takes a `cage` and produces a `(quip card _this)` like so:
16+produce a `(quip card _this)`. Here's how it would typically begin:
1717
1818```hoon
19−|= [=mark =vase]
20−^- (quip card _this)
21−...
19+++ on-poke
20+ |= [=mark =vase]
21+ ^- (quip card _this)
22+ ...
2223```
2324
24−The sample of the gate is typically specified as a cell of `mark` and `vase`
25+The sample of the gate is usually specified as a cell of `mark` and `vase`
2526rather than just `cage`, simply because it's easier to work with.
2627
2728Typically, you'd first test the `mark` with something like a
2829[wutlus](/docs/hoon/reference/rune/wut#-wutlus) `?+` expression, passing
29−unexpected `mark`s to `%default-agent`, which just crashes. We'll look at custom
30+unexpected `mark`s to `default-agent`, which just crashes. We'll look at custom
3031`mark`s in a subsequent lesson, but the basic patten looks like:
3132
3233```hoon
@@ -37,7 +38,8 @@ unexpected `mark`s to `%default-agent`, which just crashes. We'll look at custom
3738==
3839```
3940
40−After testing the `mark`, you'd typically extract the `vase` to the expected type, and then apply whatever logic you need. For example:
41+After testing the `mark`, you'd usually extract the `vase` to the expected type,
42+and then apply whatever logic you need. For example:
4143
4244```hoon
4345=/ action !<(some-type vase)
@@ -63,7 +65,7 @@ stack trace of the crash.
6365
6466As a result, you do not need to explicitly send a `%poke-ack`. Instead, you
6567would design your agent to handle only what you expect and crash in all other
66−cases. You can crash by passing the `cage` to `%default-agent`, or just with a
68+cases. You can crash by passing the `cage` to `default-agent`, or just with a
6769`!!`. In the latter case, if you want to add an error message to the stack
6870trace, you can do so like:
6971
@@ -94,7 +96,7 @@ try to pass actual data by encoding it in the nack `tang`.
9496An agent can send pokes to other agents by producing [`%poke`
9597`card`s](/docs/userspace/gall-guide/5-cards#pokes). Any agent arm apart from
9698`on-peek` and `on-save` can produce such `card`s. The arms would typically
97−produce `card`(s) like so:
99+produce the `(quip card _this)` like so:
98100
99101```hoon
100102:_ this
@@ -118,9 +120,10 @@ it came in on and the `%poke-ack` itself in a `sign:agent:gall`. Your `on-agent`
118120arm would therefore begin like so:
119121
120122```hoon
121−|= [=wire =sign:agent:gall]
122−^- (quip card _this)
123−...
123+++ on-agent
124+ |= [=wire =sign:agent:gall]
125+ ^- (quip card _this)
126+ ...
124127```
125128
126129A `sign:agent:gall` (henceforth just `sign`) is defined in `lull.hoon` as:
@@ -137,11 +140,13 @@ A `sign:agent:gall` (henceforth just `sign`) is defined in `lull.hoon` as:
137140It's basically the same as a [`gift`](/docs/userspace/gall-guide/5-cards#give),
138141but incoming instead of outgoing.
139142
140−The simplest way to handle a `%poke-ack` by passing it to `%default-agent`'s
143+The simplest way to handle a `%poke-ack` by passing it to `default-agent`'s
141144`on-agent` arm, which will just print an error message to the terminal if it's a
142−nack and otherwise do nothing. Sometimes, though, you'll want your agent to do
143−something different depending on whether the poke failed or succeeded (and
144−therefore whether it's a nack or an ack). In that case, you'd typically first test the `wire` so you can tell what the `%poke-ack` was for. You might do something like:
145+nack, and otherwise do nothing. Sometimes you'll want your agent to do something
146+different depending on whether the poke failed or succeeded (and therefore
147+whether it's a nack or an ack). In that case, you'd typically first test the
148+`wire` so you can tell what the `%poke-ack` was for. You might do something
149+like:
145150
146151```hoon
147152?+ wire (on-agent:def wire sign)
@@ -166,12 +171,12 @@ Then, you can tell whether it's an ack or a nack by testing whether the `(unit t
166171...(what to do if the poke failed)...
167172```
168173
169−Finally, you can produce any `card`s and modified agent state as appropriate and
170−return the `(quip card _this)`.
174+Finally, you can produce the `(quip card _this)`.
171175
172176## Example
173177
174−We're going to look at a couple of agents, to demonstrate both sending and receiving pokes. Here's the first, an agent that receives pokes:
178+We're going to look at a couple of agents to demonstrate both sending and
179+receiving pokes. Here's the first, an agent that receives pokes:
175180
176181### `pokeme.hoon`
177182
@@ -229,7 +234,7 @@ We're going to look at a couple of agents, to demonstrate both sending and recei
229234```
230235
231236This is a very simple agent that just has `val`, a number, in its state. It will
232−take pokes that either increment or decrement the number in its state. Here's its `on-poke` arm:
237+take pokes that either increment or decrement `val`. Here's its `on-poke` arm:
233238
234239```hoon
235240++ on-poke
@@ -256,7 +261,8 @@ with `val` incremented. If it's `%dec`, it produces `this` with `val`
256261decremented, or crashes if `val` is already zero.
257262
258263Let's try it out. Save the agent above as `/app/pokeme.hoon` in the `%base` desk
259−and `|commit %base`. Then, start it up with `|rein %base [& %pokeme]`. We can check its initial state with `dbug`:
264+and `|commit %base`. Then, start it up with `|rein %base [& %pokeme]`. We can
265+check its initial state with `dbug`:
260266
261267```
262268> 0
@@ -270,14 +276,17 @@ Next, we'll try poking it. The dojo lets you poke agents with the following synt
270276:agent-name &some-mark ['some' 'noun']
271277```
272278
273−If the `mark` part is omitted, it'll just default to `%noun`. Since our agent only takes a `%noun` mark, we can skip that. The rest will be packed in a vase by the dojo and delivered as a poke, so we can do:
279+If the `mark` part is omitted, it'll just default to `%noun`. Since our agent
280+only takes a `%noun` mark, we can skip that. The rest will be packed in a vase
281+by the dojo and delivered as a poke, so we can do:
274282
275283```
276284> :pokeme %inc
277285>=
278286```
279287
280−If we now look at the state with `dbug`, we'll see the poke was successful and it's been incremented:
288+If we now look at the state with `dbug`, we'll see the poke was successful and
289+it's been incremented:
281290
282291```
283292> 1
@@ -295,7 +304,8 @@ Let's try decrement:
295304>=
296305```
297306
298−As you can see, it's back at zero. If we try again, we'll see it fails, and the dojo will print the `tang` in the `%poke-ack` nack:
307+As you can see, it's back at zero. If we try again, we'll see it fails, and the
308+dojo will print the `tang` in the `%poke-ack` nack:
299309
300310```
301311> :pokeme %dec
@@ -420,9 +430,9 @@ Here's the `on-poke` arm:
420430```
421431
422432It's similar to `%pokeme`, except it sends two `%poke` `card`s to `%pokeme` for
423−each case. The `%inc` pokes specify a `wire` of `/inc`, and the `%dec` pokes
424−specify a `wire` of `/dec`, so we can differentiate the responses. It also has
425−the following `on-agent`:
433+each case, rather than modifying its own state. The `%inc` pokes specify a
434+`wire` of `/inc`, and the `%dec` pokes specify a `wire` of `/dec`, so we can
435+differentiate the responses. It also has the following `on-agent`:
426436
427437```hoon
428438++ on-agent
@@ -452,7 +462,8 @@ the following `on-agent`:
452462`on-agent` tests the `wire`, checks if it's a `%poke-ack`, and then prints to
453463the terminal whether it succeeded or failed.
454464
455−Save this agent to `/app/pokeit.hoon` on the `%base` desk, `|commit %base`, and start it with `|rein %base [& %pokeme] [& %pokeit]`.
465+Save this agent to `/app/pokeit.hoon` on the `%base` desk, `|commit %base`, and
466+start it with `|rein %base [& %pokeme] [& %pokeit]`.
456467
457468Let's try it out:
458469
@@ -473,7 +484,8 @@ It could tell they were increments because the `%poke-ack`s came back on the
473484>=
474485```
475486
476−Let's try decrementing `%pokeme` so it's an odd number, and then try a `%dec` via `%pokeit`:
487+Let's try decrementing `%pokeme` so it's an odd number, and then try a `%dec`
488+via `%pokeit`:
477489
478490```
479491> :pokeme %dec
@@ -502,10 +514,10 @@ took `val` to zero, and the second crashed trying to decrement below zero.
502514
503515## Exercises
504516
505−- Run through the [Example](#example) yourself on a fake ship if you've not done
517+- Run through the [example](#example) yourself on a fake ship if you've not done
506518 so already.
507519- Have a look at the `on-agent` arm of `/lib/default-agent.hoon` to see how
508− `%default-agent` handles incoming `sign`s.
520+ `default-agent` handles incoming `sign`s.
509521- Try modifying the `%pokeme` agent with another action of your choice (in
510522 addition to `%inc` and `%dec`).
511523- Try modifying the `%pokeit` agent to send your new type of poke to `%pokeme`,