@@ -106,9 +106,9 @@ need to do is produce `card`s with `%fact`s in them:
109−The `(list path)` in the `%fact` specifies which subscription `path`s to which
109+The `(list path)` in the `%fact` specifies which subscription `path`s the
110−the `%fact` should be sent. All subscribers of all `path`s specified will
110+`%fact` should be sent on. All subscribers of all `path`s specified will receive
111−receive the `%fact`. Any agent arm which produces a `(quip card _this)` can send
111+the `%fact`. Any agent arm which produces a `(quip card _this)` can send
112`%fact`s to subscribers. Most often they will be produced in the `on-poke` arm,
112`%fact`s to subscribers. Most often they will be produced in the `on-poke` arm,
113since new data will often be added in `poke`s.
113since new data will often be added in `poke`s.
@@ -129,13 +129,13 @@ from, and the `(unit ship)` specifies which ship to kick. The `(unit ship)` can
130In this case, all subscribers to the specified `path`s will be kicked.
130In this case, all subscribers to the specified `path`s will be kicked.
132−Note that `%kick`s are not exclusively sent by the agent itself - Gall can also
132+Note that `%kick`s are not exclusively sent by the agent itself - Gall itself
133−automatically kick subscribers under certain network conditions. Because of
133+can also kick subscribers under certain network conditions. Because of this,
134−this, `%kick`s are not typically interpreted as intentional, and the usual
134+`%kick`s are not assumed to be intentional, and the usual behavior is for a
135−behavior for a kicked agent is to try and resubscribe. Therefore, if you want to
135+kicked agent to try and resubscribe. Therefore, if you want to disallow a
136−disallow a particular subscriber, your agent's `on-watch` arm should reject
136+particular subscriber, your agent's `on-watch` arm should reject further
137−further subscription requests from them - your agent should not just `%kick`
137+subscription requests from them - your agent should not just `%kick` them and
138−them and call it a day.
138+call it a day.
140## Outgoing subscriptions
140## Outgoing subscriptions
@@ -148,17 +148,20 @@ it: Subscribing to other agents. This is done by `%pass`ing the target agent a
150If yor agent's subscription request is successful, updates will come in to your
150If yor agent's subscription request is successful, updates will come in to your
151−agent's `on-agent` arm on the `wire` (`/some/wire` in this example) specified.
151+agent's `on-agent` arm on the `wire` specified (`/some/wire` in this example).
152The `wire` can be anything you like - its purpose is for your agent to figure
152The `wire` can be anything you like - its purpose is for your agent to figure
153out which subscription the updates are for. The `[ship term]` pair specifies the
153out which subscription the updates are for. The `[ship term]` pair specifies the
154ship and agent you're trying to subscribe to, and the final `path` (`/some/path`
154ship and agent you're trying to subscribe to, and the final `path` (`/some/path`
155−in this example) is the subscription path to which you want to to subscribe - a
155+in this example) is the path you want to subscribe to - a `path` the target
156−`path` the target agent has defined in its `on-watch` arm.
156+agent has defined in its `on-watch` arm.
158Gall will deliver the `card` to the target agent and call that agent's
158Gall will deliver the `card` to the target agent and call that agent's
159`on-watch` arm, which will process the request [as described
159`on-watch` arm, which will process the request [as described
160above](#incoming-subscription-requests), accept or reject it, and send back
160above](#incoming-subscription-requests), accept or reject it, and send back
161−either a positive or negative `%watch-ack`. The `%watch-ack` will come back in to your agent's `on-agent` arm in a `sign`, along with the `wire` you specified (`/some/wire` in this example):
161+either a positive or negative `%watch-ack`. The `%watch-ack` will come back in
162+to your agent's `on-agent` arm in a `sign`, along with the `wire` you specified
163+(`/some/wire` in this example). Recall in the lesson on pokes, the `on-agent`
164++ on-agent
167++ on-agent
@@ -173,15 +176,11 @@ The `sign` will be of the following format:
173[%watch-ack p=(unit tang)]
176[%watch-ack p=(unit tang)]
176−How you want to handle the `%watch-ack` really depends on the particular agent. In the simplest case, you can just pass it to the `on-agent` arm of `%default-agent`:
179+How you want to handle the `%watch-ack` really depends on the particular agent.
177−
180+In the simplest case, you can just pass it to the `on-agent` arm of
179−++ on-agent on-agent:def
182−`%default-agent` will just accept it and do nothing apart from printing the
181+`default-agent`, which will just accept it and do nothing apart from printing
183−error in the `%watch-ack` `tang` if it's a nack. You shouldn't have your agent
182+the error in the `%watch-ack` `tang` if it's a nack. You shouldn't have your
184−crash on a `%watch-ack` - even if it's a nack your agent should process it
183+agent crash on a `%watch-ack` - even if it's a nack your agent should process it
185successfully. If you wanted to apply some additional logic on receipt of the
184successfully. If you wanted to apply some additional logic on receipt of the
186`%watch-ack`, you'd typically first test the `wire`, then test whether it's a
185`%watch-ack`, you'd typically first test the `wire`, then test whether it's a
187`%watch-ack`, then test whether it's an ack or a nack and do whatever's
186`%watch-ack`, then test whether it's an ack or a nack and do whatever's
@@ -213,10 +212,9 @@ an error message fed into the `on-fail` arm of your agent.
213## Receiving updates
212## Receiving updates
215Assuming the `%watch` succeeded, your agent will now begin receiving any
214Assuming the `%watch` succeeded, your agent will now begin receiving any
216−`%fact`s the agent to which you've subscribed publishes on the path to which
215+`%fact`s the other agent publishes on the path to which you've subscribed. These
217−you've subscribed. These `%fact`s will also come in to your agent's `on-agent`
216+`%fact`s will also come in to your agent's `on-agent` arm in a `sign`, just like
218−arm in a `sign`, just like the initial `%watch-ack`. The `%fact` `sign` will
217+the initial `%watch-ack`. The `%fact` `sign` will have the following format:
219−have the following format:
222[%fact =cage]
220[%fact =cage]
@@ -606,7 +604,8 @@ currently exists, getting the new subscriber up to date.
608This is the subscriber agent. Since it's just for demonstrative purposes, it has
606This is the subscriber agent. Since it's just for demonstrative purposes, it has
609−no state and just prints updates it receives. In practice it would probably keep the `tasks` map it receives in its own state, and then update it as it receives new
607+no state and just prints updates it receives. In practice it would keep the
608+`tasks` map it receives in its own state, and then update it as it receives new
612The `on-poke` arm is fairly simple - it accepts two pokes, to either `[%sub ~some-ship]` or `[%unsub ~some-ship]`.
611The `on-poke` arm is fairly simple - it accepts two pokes, to either `[%sub ~some-ship]` or `[%unsub ~some-ship]`.
@@ -618,7 +617,10 @@ failed, as well as printing a message when it gets kicked. When it receives a
619### Trying it out
618### Trying it out
621−We're going to try this between two different ships. The first ship will be the usual fakezod. We'll add both `mark` files, the `/sur` file, and the `todo.hoon` agent to the `%base` desk of our fakezod, putting them in the following directories:
620+We're going to try this between two different ships. The first ship will be the
621+usual fakezod. We'll add both `mark` files, the `/sur` file, and the `todo.hoon`
622+agent to the `%base` desk of our fakezod, putting them in the following
@@ -644,7 +646,8 @@ Now we need to spin up another fake ship. We'll use `~nut` in this example:
644urbit -F nut
646urbit -F nut
647−Once it's booted, we can `|mount %base` and then add just the `update.hoon` mark file, the `/sur` file, and the `todo-watcher.hoon` agent like so:
649+Once it's booted, we can `|mount %base` and then add just the `update.hoon` mark
650+file, the `/sur` file, and the `todo-watcher.hoon` agent like so:
@@ -827,8 +830,9 @@ was rejected because `~nut` is no longer in `friends`:
828## Exercises
831## Exercises
830−- Have a look at the [Strings Guide](/docs/hoon/guides/strings) if you're
833+- Have a look at the [Strings Guide](/docs/hoon/guides/strings) if you're not
831 already familiar with decoding/encoding atoms in strings.
834 already familiar with decoding/encoding atoms in strings.
832−- Try running through the [Example](#example) yourself, if you've not done so already.
835+- Try running through the [example](#example) yourself, if you've not done so
833- Try modifying `%todo-watcher` to recording the data it receives in its state,
837- Try modifying `%todo-watcher` to recording the data it receives in its state,
834 rather than simply printing it to the terminal.
838 rather than simply printing it to the terminal.