@@ -10,11 +10,9 @@ Gall is the Arvo vane responsible for handling user space applications. When wri
1010
1111The core of a gall app is a door which has two parts of its subject, the first a `bowl:gall` which contains a lot of standard things used by gall apps, the second a type containing app state information.
1212
13−Vanes in Arvo communicate by means of `moves`. When a move is produced by an arm in a gall app, it's dispatched by Arvo to the correct handler for the request, be it another application or another vane. A `move` is pair of `bone` and `card`. These are essential components to understand when learning to use gall.
13+Vanes in Arvo communicate by means of `moves`. When a move is produced by an arm in a gall app, it's dispatched by Arvo to the correct handler for the request, be it another application or another vane. A `move` is pair of `bone` and `card`. These are essential components to understand when learning to use gall.
1414
15−A `bone` is an opaque cause that initiates a request. When constructing a `move` you can often use `ost.bowl` and when responding to an incoming `move` you can use the `bone` in that `move` to construct your response.
16−
17−[comment]: # (If `bone`s are opaque then it doesn't make sense to me that you would be able to use one to make your response)
15+A `bone` is an opaque cause that initiates a request. When constructing a `move` you can often use `ost.bowl` and when responding to an incoming `move` you can use the `bone` in that `move` to construct your response.
1816
1917A `card` is the effect or event that is being requested. Each application should define the set of `cards` it can produce. Here is an excerpt from `clock.hoon` showing its `cards`
2018
@@ -35,7 +33,9 @@ Gall applications can have a number of arms that get called depending on the inf
3533
3634### ++prep
3735
38−`++prep` is the arm that is called when an application is first started or when it's updated. This arm should be a gate that takes a `unit` of a noun and provides a way, if necessary, to make any changes to the application's data required by an upgrade. Often when developing an application you will not initially care about the data. Here is a sample `++prep` arm that will simply throw away the previous application state.
36+`++prep` is the arm that is called when an application is first started or when it's updated. This arm should be a gate that takes a `unit` of a noun and provides a way, if necessary, to make any changes to the application's data required by an upgrade. As a reminder, a `unit` is a type that may contain another type or it might contain `~`. They are used when there may or may not be some data available.
37+
38+Often when developing an application you will not initially care about the data. Here is a sample `++prep` arm that will simply throw away the previous application state.
3939
4040```
4141++ prep
@@ -43,8 +43,6 @@ Gall applications can have a number of arms that get called depending on the inf
4343 `(quip move _+>.$)`[~ +>.$]
4444```
4545
46−[comment]: # (Up until this point in the Hoon tutorial it looks like the only place `unit`s have been mentioned is in 1.9, and it isn't defined there either. So we need to throw in a definition somewhere.)
47−
4846### ++poke
4947
5048`++poke` is one of the primary arms used when building a Gall application. A `poke` is often a request to perform some operation that the application was designed for. These are requests from outside the application. `++poke` will get called with the raw noun data which can then be inspected to perform the requested actions with.
@@ -57,9 +55,7 @@ Many arms, `++poke` included, have variants that end in the name of a mark e.g.
5755
5856### ++peer
5957
60−`++peer` is used to handle subscriptions. When something subscribes to your application this arm will run. Your outgoing subscriptions will not be tracked automatically but incoming ones will live in `sup.bowl` so that you can send information to them when required.
61−
62−[comment]: # (What is the "something" that can subscribe to the application? e.g. other Gall applications, Ames, other ships, etc?)
58+`++peer` is used to handle subscriptions. When something subscribes to your application this arm will run. The something could be another Gall application on your ship or another ship or a tile from landscape or anything else that is able to communicate with Gall. Your outgoing subscriptions will not be tracked automatically but incoming ones will live in `sup.bowl` so that you can send information to them when required.
6359
6460### ++pull
6561
@@ -79,8 +75,6 @@ Many arms, `++poke` included, have variants that end in the name of a mark e.g.
7975
8076### ++sigh
8177
82−`++sigh` gets called when eyre has a response to an http request made by our application.
83−
84−[comment]: # (What is the preferred style for the name of vanes? Looking over the docs, I seen them capitalized, all lowercase, and written like `%eyre`)
78+`++sigh` gets called when Eyre has a response to an http request made by our application.
8579
8680Let's take a look in the next section at an example Gall app.