@@ -4,17 +4,19 @@ weight = 0
44template = "doc.html"
55+++
66
7−Gall is the Arvo vane responsible for handling user space applications. When writing a Gall application there are several thinks you will need to understand.
7+Gall is the Arvo vane responsible for handling user space applications. When writing a Gall application there are several things you will need to understand.
88
99## bowl and moves
1010
11−The core of a gall app is a door which has two parts of it's 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.
11+The 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
1313Vanes 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 an incoming `move` you can use the `bone` in that `move` to construct 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.
1616
17−A `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 it's `cards`
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)
18+
19+A `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`
1820
1921```
2022+$ card
@@ -41,11 +43,13 @@ Gall applications can have a number of arms that get called depending on the inf
4143 `(quip move _+>.$)`[~ +>.$]
4244```
4345
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+
4448### ++poke
4549
4650`++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.
4751
48−Many arms `++poke` included, have variants that end in the name of a mark e.g. `++poke-noun`. Which one gets called will be base on what mark was used to create the poke. Gall will attempt to use the most specific arm it can find, eventually falling back to `++poke` if no matching mark arm is found. Use of these mark arms however is now discouraged.
52+Many arms, `++poke` included, have variants that end in the name of a mark e.g. `++poke-noun`. Which one gets called will be based on which mark was used to create the poke. Gall will attempt to use the most specific arm it can find, eventually falling back to `++poke` if no matching mark arm is found. Use of these mark arms, however, is now discouraged.
4953
5054### ++coup
5155
@@ -55,6 +59,8 @@ Many arms `++poke` included, have variants that end in the name of a mark e.g. `
5559
5660`++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.
5761
62+[comment]: # (What is the "something" that can subscribe to the application? e.g. other Gall applications, Ames, other ships, etc?)
63+
5864### ++pull
5965
6066`++pull` is run when someone unsubscribes from your application, this is used to run any changes needed for your application when they unsubscribed. Their removal from `sup.bowl` is handled for you.
@@ -75,4 +81,6 @@ Many arms `++poke` included, have variants that end in the name of a mark e.g. `
7581
7682`++sigh` gets called when eyre has a response to an http request made by our application.
7783
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`)
85+
7886Let's take a look in the next section at an example Gall app.