@@ -5,6 +5,8 @@ sort: 5
55title: Subscriptions
66---
77
8+# Subscriptions
9+
810We've dealt fairly extensively with "poke" messages to an app,
911but these are somewhat limited. A poke is a one-way message, but
1012more often we want to subscribe to updates from another app. You
@@ -75,49 +77,48 @@ And secondly, `:examples-sink`:
7577
7678Cheat sheet:
7779
78−```
79−- `&` can either be the boolean true (along with `%.y`, `0`), or
80− the irregular wide form of the `$&` rune, which computes the
81− logical 'and' operation on its two children.
80+- `&` (pam) can either be the boolean true (along with `%.y`, `0`), or
81+ the irregular wide form of the `?&` ([wutpam](/hoon/twig/wut-test/pam-and)) rune, which computes the
82+ logical `AND` operation on its two children.
8283
8384- Similar to `&`,`|` is either the boolean false (along with `%.n` and `1`), or
84− the irregular short for of `?|`, which computes the logical 'or' operation on
85− its two children
85+ the irregular short for of `?|` ([wutbar](/hoon/twig/wut-test/bar-or)), which computes logical `OR` on
86+ its two children.
8687
87−- `!` is the irregular wide form of `?!`, which computes the logical `not` on
88− its child.
88+- `!` is the irregular wide form of `?!` ([wutzap](/hoon/twig/wut-test/zap-not/)), which computes
89+ logical `NOT` on its child.
8990
90−- `?~` is basically an if-then-else statement that checks whether condition `p`
91− is `~` (null). `?~` is slightly different to `?:(~ %tru %fal) in that it
92− reduces to ?:($=(%type value) %tru %false). `$=` tests whether value `q`
93− falls within type `p`. One thing to watch out for in hoon: if you do `?~`, it
94− affects the type of the conditional value: XXexample
91+- `?~` ([wutsig](/hoon/twig/wut-test/sig-ifno/)) is basically an if-then-else that checks whether condition `p`
92+ is `~` (null). `?~` is slightly different from `?:(~ %tru %fal)` in that `?~`
93+ reduces to `?:($=(%type value) %tru %false)`. `$=` ([buctis](/hoon/twig/buc-mold/tis-coat/)) tests whether
94+ value `q` is of type `p`.
95+ <!--One thing to watch out for in hoon: if you do `?~`, it
96+ affects the type of the conditional value: XXexample-->
9597
96−- `:_` is just an inverted `:-`: all it does is accept children `p` and `q` and
97− produce an inverted tuple of the two, `[q p]`.
98+- `:_` ([colcab](/hoon/twig/col-cell/cab-scon/)) is inverted `:-`: it accepts `p` and `q`, and produces `[q p]`.
9899
99−- `++bowl` is the type of our system state within our app. For example, it
100− includes things like `our`, the ship name of the host, and `now`, the
100+- `++bowl` is the type of the system state within our app. For example, it
101+ includes things like `our`, the name of the host urbit, and `now`, the
101102 current time.
102103
103−- `$%` is a type constructor that defines a type composed of `n`
104+- `$%` ([buccen](/hoon/twig/buc-mold/cen-book/)) is a type constructor: it defines a new type, composed of `n`
104105 types that it is passed. For example `$% @ * ^ ==` is the
105− type of either `@`, `*`, or a cell `^`. XX this a union, right?
106+ type of either `@`, `*`, or a cell `^`. <!--XX this is a union, right?-->
106107
107−- You may have noticed the separate `|%` above the application
108− core `|_`. We usually put our types in another core on top of the
108+- You may have noticed the separate `|%` ([barcen](/hoon/twig/bar-core/cen-core/)) above the application
109+ core `|_` ([barcab](/hoon/twig/bar-core/cab-door/). We usually put our types in another core on top of the
109110 application core. We can access these type from our `|_`
110− because in hoon.hoon files, all cores are =>'ed (called) against
111− each other. Thus the `|%` with the types is in the context of
112− the `|_`, as it lies above it: hoon.hoon `=> |% w types =>
111+ because in `hoon.hoon` files, all cores are called against
112+ each other. (The shorthand for 'called' is `=>`.) Thus, the
113+ `|%` with the types is in the context of the `|_`, as it lies
114+ above it: `hoon.hoon` `=> |% w types =>
113115 |_`
114116
115117
116−```
117−
118118Here's some sample output of the two working together:
119119
120120```
121+
121122~fintud-macrep:dojo> |start %examples-source
122123>=
123124~fintud-macrep:dojo> |start %examples-sink
@@ -140,6 +141,7 @@ Here's some sample output of the two working together:
140141~fintud-macrep:dojo> :examples-source 7
141142[%received-data 7]
142143>=
144+
143145```
144146
145147###:examples-source
@@ -158,8 +160,8 @@ going to sending one kind of move. The `%diff` move is a
158160subscription update, and its content is marked data which gall
159161routes to our subscribers.
160162
161−This is a slightly different kind of move than we've dealt with
162−so far. It's producing a result rather than calling other code
163+This is a slightly different kind of move than [we've dealt with
164+so far](/arvo/network). It's producing a result rather than calling other code
163165(i.e. it's a return rather than a function call), so if you
164166recall the discussion of ducts, a layer gets popped off the duct
165167rather than added to it. This is why no wire is needed for the
@@ -199,7 +201,7 @@ who are subscribed on a path that begins with the given path.
199201
200202Now we have the list of relevant subscribers. This a list of
201203triples, `{bone @p path}`, where the only thing we really need is
202−the bone because we don't care what urbit they are or what exact
204+the bone, because we don't need to know their urbit or what exact
203205path they subscribed on. Thus, our transformer function takes
204206`{o/bone *}` and produces `[o %diff %noun arg]`, which is a move
205207that provides bone `o` with this subscription update: `[%noun
@@ -228,7 +230,7 @@ when you subscribed, then the cancellation will happen correctly.
228230
229231The only state we need for `:examples-sink` is a boolean to indicate whether
230232we're already subscribed to `:examples-source`. We use `available/?`,
231−where `?` is the sign of type boolean (similar to `*`, `@`) (which defaults to true).
233+where `?` is the sign of type boolean (similar to `*`, `@`), which defaults to true (that is, `0`).
232234
233235In `++poke-noun` we check our input to see both if it's `%on` and
234236we're available. If so, we produce the move to subscribe to
@@ -253,8 +255,8 @@ as the one we originally subscribed on.
253255
254256We also set `available` to true (`&`).
255257
256−If neither of these cases are true, then we just print out our
257−current subscription state and do nothing.
258+If neither of these cases are true, then we print our
259+current subscription state.
258260
259261`++diff-noun` is called when we get a `%diff` update along a
260262subscription with a mark of `noun`. `++diff-noun` is given the
@@ -265,7 +267,7 @@ print out the data.
265267`++reap` is called when we receive an acknowledgment as to
266268whether the subscription was handled successfully. You can
267269remember that `++reap` is the counterpart to `++peer` as it's
268−almost spelled the same as 'peer' backwards. Similarly, `coup` is
270+pronounced like 'peer' backwards. Similarly, `coup` is
269271similar to 'poke' backwards.
270272
271273Moving forward, `++reap` is given the wire we attempted to