@@ -10,9 +10,7 @@ Now we've learned enough hoon to do more interesting things.
1010Let's get our planets to talk to each other.
1111
1212All we've written up until now are just shell
13−commands that produce a value and then disappear. We need an
14−actual app to listen for messages from another planet. Let's
15−take a look at a very basic app that does this.
13+commands that produce a value and then disappear. To listen for and receive messages from other planets, we'll need an app--let's look at a very simple one:
1614
1715```
1816:: There is no love that is not an echo
@@ -21,10 +19,10 @@ take a look at a very basic app that does this.
2119 ::
2220/? 314
2321!:
24−|_ [bowl state=~]
22+|_ {bowl state/$~}
2523++ poke-noun
26− |= arg=*
27− ^- [(list) _+>.$]
24+ |= arg/*
25+ ^- {(list) _+>.$}
2826 ~& [%argument arg]
2927 [~ +>.$]
3028--
@@ -74,13 +72,12 @@ we'll get to the correct way later on.
7472
7573But what does `++poke-noun` produce? Recall that `^-` casts to a
7674type. In this case, it's declaring that end result of the
77−function will be of type `[(list) _+>.$]`. But what does this
75+function will be of type `{(list) _+>.$}`. But what does this
7876mean?
7977
8078The phrase to remember is "a list of moves and our state". Urbit
81−is a message passing system XX should we mention event
82−driven operating system XX, so whenever we want to do something that
83−interacts with the rest of the system we send a message. Thus, a
79+is a message passing system, so whenever we want to do something that
80+interacts with the rest of the system, we send a message. Thus, a
8481move is arvo's equivalent of a syscall. The first thing that
8582`++poke-noun` produces is a list of messages, called
8683"moves". In this case, we don't actually want the system to do
@@ -99,11 +96,11 @@ number, and then print out the square of that number.
9996```
10097/? 314
10198!:
102−|_ [bowl state=~]
99+|_ {bowl state=~}
103100::
104101++ poke-atom
105− |= arg=@
106− ^- [(list) _+>.$]
102+ |= arg/@
103+ ^- {(list) _+>.$}
107104 ~& [%square (mul arg arg)]
108105 [~ +>.$]
109106--
@@ -114,6 +111,8 @@ arbitrary nouns because we can only square atoms (integers, in
114111this case an unsigned one). Thus, our argument is now `arg=@`.
115112Secondly, it's `++poke-atom` rather than `++poke-noun`.
116113
114+# Intro to marks
115+
117116Are there other `++poke`s? Yes. In fact, `noun` and
118117`atom` are just two of arbitrarily many "marks". A mark is
119118fundamentally a type definition, but accessible at the arvo
@@ -156,31 +155,32 @@ pipeline, so we'll be getting quite used to them.
156155 previous section).
157156
158157- One way of representing strings is with double quoted strings
159− called "tapes". The hoon type is `++tape`, and there is a
160− corresponding mark with the same name. Write an app that
158+ called "tapes". The hoon type is `++tape`, Write an app that
161159 accepts a tape and prints out `(flop argument)`, where
162160 `argument` is the input. What does this do?
163161
164162
165−Let's write our first network message! Here's `/ape/pong.hoon`:
163+# Sending a message to another ship
164+
165+Let's write our first network message! Here's `/app/pong.hoon`:
166166
167167```
168168/? 314
169169|%
170− ++ move ,[bone term wire *]
170+ ++ move {bone term wire *}
171171--
172172!:
173−|_ [bowl state=~]
173+|_ {bowl state=$~}
174174::
175175++ poke-urbit
176− |= to=@p
176+ |= to/@p
177177 ^- [(list move) _+>.$]
178178 [[[ost %poke /sending [to %pong] %atom 'howdy'] ~] +>.$]
179179::
180180++ poke-atom
181− |= arg=@
182− ^- [(list move) _+>.$]
183− ~& [%receiving (,@t arg)]
181+ |= arg/@
182+ ^- (list move) _+>.$}
183+ ~& [%receiving (@t arg)]
184184 [~ +>.$]
185185::
186186++ coup |=(* [~ +>.$])
@@ -206,15 +206,13 @@ see, on the foreign urbit, this output:
206206```
207207
208208Most of the code should be straightforward. In `++poke-atom`,
209−the only new thing is the expression `(,@t arg)`. As we already
210−know, `@t` is the type of "cord" text strings. `,` is the
211−irregular short form of `$,`an operator that turns a type into a
212−validator function (called a "clam" in hoon) -- that is, a
213−function whose domain is all nouns and range is the given type.
209+the only new thing is the expression `(@t arg)`. As we already
210+know, `@t` is the type of "cord" text strings. In Hoon, when types are called as functions, they serve as a validator function (called a "clam" in hoon) -- that is, a function whose domain is all nouns and range is the given type.
211+
214212In simpler terms, if a validator function is passed a value that
215213falls within its type, that value is produced. Otherwise, it
216214produces the default value (aka the "bunt") of its type. Here we call
217−this `,@t` function on the argument. This coerces the argument
215+this `@t` function on the argument. This coerces the argument
218216to text, so that we can print it out prettily no matter what
219217we're passed.
220218
@@ -236,10 +234,9 @@ with one element:
236234
237235The general form of a move is
238236
239− >-app/vane-specific part of move
237+-arvo part---->
240238`[bone term wire *]`
241− -arvo part---->
242− of move
239+ >-app/vane-specific part of move
243240
244241Or, in pseudo-code:
245242
@@ -265,16 +262,14 @@ as a keystroke, network packet, file change, or timer event.
265262When arvo is given this event, it routes the event to appropriate
266263kernel module for handling.
267264
268−XX[short explanation of the composition of arvo should be here.]
269−
270265Sometimes, the module can immediately handle the event and
271266produce any necessary results. For example, when we poked the
272267`++poke-atom` arm above, we poked %gall, our application server,
273268which was able to respond to our poke directly. When the module
274−cannot service the request itself, it sends instructions to the other kernel
275−module or application to do a specified action, and produces the
276−result from that. Furthermore, when one module sends a message to another kernel
277−module or application, it also sends along the duct it was given
269+cannot service the request itself, it sends instructions to another kernel
270+module or application (the the %gall module) to do a specified action, and produces the result from that.
271+
272+Furthermore, when one module sends a message to another kernel module or application, it also sends along the duct it was given
278273with its new wire tacked onto the end. Now the duct has two entries,
279274with the unix even on the bottom and the kernel module that
280275handled it next. This process can continue indefinitely, adding
@@ -296,7 +291,7 @@ trying to send. Thus, we say to send the network message along the given bone
296291##### Wire ('tack on new layer to duct')
297292
298293Of course, we have to push a new layer onto our duct
299−before passing it along (or responding to it directly) anywhere This
294+before passing it along (or responding to it directly) anywhere. This
300295layer can have any data we want in it, but we don't need anything
301296specific here, so we just use the wire `/sending`
302297(`/elem1/elem2/elem n` is one syntax used to create `++path`s and
@@ -318,8 +313,6 @@ the name of the syscall. Common ones include: `%poke`, to
318313message an app; `%warp`, to read from the filesystem; `%wait`, to
319314set a timer; and `%them`, to send an http request.
320315
321−XXDescribe where they can find a list of these things.
322−
323316The general form ends with `*` (a noun) since each type of move takes
324317different data. In our case, a `%poke` move takes a target
325318(urbit and app) and marked data and pokes the arm of the
@@ -342,7 +335,7 @@ apps on different urbits.
342335- Extend either of the apps in the first two exercises to accept
343336 input over the network in the same way as `pong`.
344337
345−- Modify `pong` to print out a message when it receives an ack.
338+- Modify `pong` to print out a message when it receives acknowledgement.
346339
347340- Write two apps, `even` and `odd`. When you pass an atom to
348341 `even`, check whether it's even. If so, divide it by two and
@@ -350,9 +343,7 @@ apps on different urbits.
350343 an atom, check whether it's equal to one. If so, terminate,
351344 printing "%success". Otherwise, check whether it's odd. If
352345 so, multiply it by three, add one, and recurse; otherwise, poke
353− `even` with it. multiply it by three and add one. When either
354− app receives a number, print it out along with the name of the
355− app. In the end, you should be able to watch Collatz's
346+ `even` with it. When either app receives a number, print it out along with the name of the app. In the end, you should be able to watch Collatz's
356347 conjecture play out between the two apps. Sample output:
357348
358349```