@@ -4,17 +4,19 @@ weight = 0
4template = "doc.html"
4template = "doc.html"
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.
9## bowl and moves
9## bowl and moves
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.
13Vanes 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.
13Vanes 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.
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.
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)
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`
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`
@@ -41,11 +43,13 @@ Gall applications can have a number of arms that get called depending on the inf
41 `(quip move _+>.$)`[~ +>.$]
43 `(quip move _+>.$)`[~ +>.$]
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.)
46`++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.
50`++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.
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.
@@ -55,6 +59,8 @@ Many arms `++poke` included, have variants that end in the name of a mark e.g. `
56`++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.
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.
62+[comment]: # (What is the "something" that can subscribe to the application? e.g. other Gall applications, Ames, other ships, etc?)
60`++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.
66`++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. `
76`++sigh` gets called when eyre has a response to an http request made by our application.
82`++sigh` gets called when eyre has a response to an http request made by our application.
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`)
78Let's take a look in the next section at an example Gall app.
86Let's take a look in the next section at an example Gall app.