@@ -13,20 +13,21 @@ take - a `%poke-ack`.
14Whenever something tries to poke your agent, Gall calls your agent's `on-poke`
14Whenever something tries to poke your agent, Gall calls your agent's `on-poke`
15arm and give it the `cage` from the poke as its sample. The `on-poke` arm will
15arm 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:
19−|= [=mark =vase]
20+ |= [=mark =vase]
20−^- (quip card _this)
21+ ^- (quip card _this)
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`
25rather than just `cage`, simply because it's easier to work with.
26rather than just `cage`, simply because it's easier to work with.
27Typically, you'd first test the `mark` with something like a
28Typically, you'd first test the `mark` with something like a
28[wutlus](/docs/hoon/reference/rune/wut#-wutlus) `?+` expression, passing
29[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
30`mark`s in a subsequent lesson, but the basic patten looks like:
31`mark`s in a subsequent lesson, but the basic patten looks like:
@@ -37,7 +38,8 @@ unexpected `mark`s to `%default-agent`, which just crashes. We'll look at custom
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:
43=/ action !<(some-type vase)
45=/ action !<(some-type vase)
@@ -63,7 +65,7 @@ stack trace of the crash.
64As a result, you do not need to explicitly send a `%poke-ack`. Instead, you
66As a result, you do not need to explicitly send a `%poke-ack`. Instead, you
65would design your agent to handle only what you expect and crash in all other
67would 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
67`!!`. In the latter case, if you want to add an error message to the stack
69`!!`. In the latter case, if you want to add an error message to the stack
68trace, you can do so like:
70trace, you can do so like:
@@ -94,7 +96,7 @@ try to pass actual data by encoding it in the nack `tang`.
94An agent can send pokes to other agents by producing [`%poke`
96An agent can send pokes to other agents by producing [`%poke`
95`card`s](/docs/userspace/gall-guide/5-cards#pokes). Any agent arm apart from
97`card`s](/docs/userspace/gall-guide/5-cards#pokes). Any agent arm apart from
96`on-peek` and `on-save` can produce such `card`s. The arms would typically
98`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:
@@ -118,9 +120,10 @@ it came in on and the `%poke-ack` itself in a `sign:agent:gall`. Your `on-agent`
118arm would therefore begin like so:
120arm would therefore begin like so:
121−|= [=wire =sign:agent:gall]
124+ |= [=wire =sign:agent:gall]
122−^- (quip card _this)
125+ ^- (quip card _this)
126A `sign:agent:gall` (henceforth just `sign`) is defined in `lull.hoon` as:
129A `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:
137It's basically the same as a [`gift`](/docs/userspace/gall-guide/5-cards#give),
140It's basically the same as a [`gift`](/docs/userspace/gall-guide/5-cards#give),
138but incoming instead of outgoing.
141but incoming instead of outgoing.
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
141`on-agent` arm, which will just print an error message to the terminal if it's a
144`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
145+nack, and otherwise do nothing. Sometimes you'll want your agent to do something
143−something different depending on whether the poke failed or succeeded (and
146+different depending on whether the poke failed or succeeded (and therefore
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:
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
147?+ wire (on-agent:def wire sign)
152?+ 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
166...(what to do if the poke failed)...
171...(what to do if the poke failed)...
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)`.
172## Example
176## Example
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:
176### `pokeme.hoon`
181### `pokeme.hoon`
@@ -229,7 +234,7 @@ We're going to look at a couple of agents, to demonstrate both sending and recei
231This is a very simple agent that just has `val`, a number, in its state. It will
236This 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:
235++ on-poke
240++ on-poke
@@ -256,7 +261,8 @@ with `val` incremented. If it's `%dec`, it produces `this` with `val`
256decremented, or crashes if `val` is already zero.
261decremented, or crashes if `val` is already zero.
258Let's try it out. Save the agent above as `/app/pokeme.hoon` in the `%base` desk
263Let'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`:
@@ -270,14 +276,17 @@ Next, we'll try poking it. The dojo lets you poke agents with the following synt
270:agent-name &some-mark ['some' 'noun']
276:agent-name &some-mark ['some' 'noun']
279+If the `mark` part is omitted, it'll just default to `%noun`. Since our agent
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:
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:
276> :pokeme %inc
284> :pokeme %inc
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:
@@ -295,7 +304,8 @@ Let's try decrement:
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:
301> :pokeme %dec
311> :pokeme %dec
@@ -420,9 +430,9 @@ Here's the `on-poke` arm:
422It's similar to `%pokeme`, except it sends two `%poke` `card`s to `%pokeme` for
432It'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
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
424−specify a `wire` of `/dec`, so we can differentiate the responses. It also has
435+differentiate the responses. It also has the following `on-agent`:
425−the following `on-agent`:
428++ on-agent
438++ on-agent
@@ -452,7 +462,8 @@ the following `on-agent`:
452`on-agent` tests the `wire`, checks if it's a `%poke-ack`, and then prints to
462`on-agent` tests the `wire`, checks if it's a `%poke-ack`, and then prints to
453the terminal whether it succeeded or failed.
463the terminal whether it succeeded or failed.
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]`.
457Let's try it out:
468Let's try it out:
@@ -473,7 +484,8 @@ It could tell they were increments because the `%poke-ack`s came back on the
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`
479> :pokeme %dec
491> :pokeme %dec
@@ -502,10 +514,10 @@ took `val` to zero, and the second crashed trying to decrement below zero.
503## Exercises
515## Exercises
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
506 so already.
518 so already.
507- Have a look at the `on-agent` arm of `/lib/default-agent.hoon` to see how
519- 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.
509- Try modifying the `%pokeme` agent with another action of your choice (in
521- Try modifying the `%pokeme` agent with another action of your choice (in
510 addition to `%inc` and `%dec`).
522 addition to `%inc` and `%dec`).
511- Try modifying the `%pokeit` agent to send your new type of poke to `%pokeme`,
523- Try modifying the `%pokeit` agent to send your new type of poke to `%pokeme`,