@@ -0,0 +1,80 @@
1++++
2+title = "Gall"
3+weight = 0
4+template = "doc.html"
5++++
6+
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.
8+
9+## bowl and moves
10+
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.
12+
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.
14+
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+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`
18+
19+```
20++$ card
21+ $% [%poke wire dock poke]
22+ [%http-response =http-event:http]
23+ [%connect wire binding:eyre term]
24+ [%diff %json json]
25+ ==
26+```
27+
28+Each `card` is a pair of a tag and a noun. The tag indicates what the event being triggered is and the noun is any data required for that event.
29+
30+## Arms
31+
32+Gall applications can have a number of arms that get called depending on the information they are sent.
33+
34+### ++prep
35+
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.
39+
40+```
41+++ prep
42+ |= a=(unit *)
43+ `(quip move _+>.$)`[~ +>.$]
44+```
45+
46+### ++poke
47+
48+`++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.
49+
50+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.
51+
52+### ++coup
53+
54+`++coup` is a response handler for any pokes our application sent out.
55+
56+### ++peer
57+
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.
59+
60+### ++pull
61+
62+`++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.
63+
64+### ++quit
65+
66+`++quit` gets called when a subscription is dropped. Often you will just want to resubscribe when this happens.
67+
68+### ++reap
69+
70+`++reap` is to `++peer` as `++coup` is to `++poke`, that is to say it's the arm that gets run in acknowledgment of outgoing subscription requests.
71+
72+### ++diff
73+
74+`++diff` gets called when an application you are subscribed to has an update. It could either be an entirely new set of data for that application or an update to existing data.
75+
76+### ++sigh
77+
78+`++sigh` gets called when Eyre has a response to an http request made by our application.
79+
80+Let's take a look in the next section at an example Gall app.