@@ -18,9 +18,9 @@ very simple union in the `vase` for incoming pokes:
18=/ action !<(?(%inc %dec) vase)
18=/ action !<(?(%inc %dec) vase)
21−A real Gall agent, however, is likely to have a more complicated API. The most
21+A real Gall agent is likely to have a more complicated API. The most common
22−common approach is to define a head-tagged union of all possible poke types the
22+approach is to define a head-tagged union of all possible poke types the agent
23−agent will accept, and another for all possible updates it might send out to
23+will accept, and another for all possible updates it might send out to
24subscribers. Rather than defining these types in the agent itself, you would
24subscribers. Rather than defining these types in the agent itself, you would
25typically define them in a separate core saved in the `/sur` directory of the
25typically define them in a separate core saved in the `/sur` directory of the
26desk. The `/sur` directory is short for "**s**truct**ur**es", and is the
26desk. The `/sur` directory is short for "**s**truct**ur**es", and is the
@@ -28,8 +28,8 @@ canonical location for userspace type definitions.
29With this approach, your agent can simply import the structure file and make use
29With this approach, your agent can simply import the structure file and make use
30of its types. Additionally, if someone else wants to write an agent that
30of its types. Additionally, if someone else wants to write an agent that
31−interfaces with yours, they can simply include your structure file in their own
31+interfaces with yours, they can include your structure file in their own desk
32−desk and easily interface with your agent's API.
32+and easily interact with your agent's API.
34#### Example
34#### Example
@@ -126,9 +126,9 @@ Let's break this down a bit. Firstly, our `on-poke` arm includes a
126core with a `$` arm that's computed immediately. We extract the `vase` to the
126core with a `$` arm that's computed immediately. We extract the `vase` to the
127`action:todo` type and immediately pass it to the `handle-poke` arm of the core
127`action:todo` type and immediately pass it to the `handle-poke` arm of the core
128created with the barket. This `handle-poke` arm tests what kind of `action` it's
128created with the barket. This `handle-poke` arm tests what kind of `action` it's
129−received by checking its head, updates the state, and also sends an update to
129+received by checking its head. It then updates the state, and also sends an
130−subscribers, as appropriate. Don't worry too much about the `%give` `card` for
130+update to subscribers, as appropriate. Don't worry too much about the `%give`
131−now - we'll cover subscriptions in the next lesson.
131+`card` for now - we'll cover subscriptions in the next lesson.
133Notice that the `handle-poke` arm produces a `(quip card _state)` rather than
133Notice that the `handle-poke` arm produces a `(quip card _state)` rather than
134`(quip card _this)`. The call to `handle-poke` is also part of the following
134`(quip card _this)`. The call to `handle-poke` is also part of the following
@@ -168,7 +168,9 @@ what such `mark`s represent, or considered writing custom ones.
169Formally, marks are file types in the Clay filesystem. They correspond to mark
169Formally, marks are file types in the Clay filesystem. They correspond to mark
170files in the `/mar` directory of a desk. The `%noun` mark, for example,
170files in the `/mar` directory of a desk. The `%noun` mark, for example,
171−corresponds to the `/mar/noun.hoon` file. Mark files define the actual hoon data type for the file (e.g. a `*` noun for the `%noun` mark), but they also specify some extra things:
171+corresponds to the `/mar/noun.hoon` file. Mark files define the actual hoon data
172+type for the file (e.g. a `*` noun for the `%noun` mark), but they also specify
173- Methods for converting between the mark in question and other marks.
175- Methods for converting between the mark in question and other marks.
174- Revision control functions like patching, diffing, merging, etc.
176- Revision control functions like patching, diffing, merging, etc.
@@ -176,14 +178,14 @@ corresponds to the `/mar/noun.hoon` file. Mark files define the actual hoon data
176Aside from their use by Clay for storing files in the filesystem, they're also
178Aside from their use by Clay for storing files in the filesystem, they're also
177used extensively for exchanging data with the outside world, and for exchanging
179used extensively for exchanging data with the outside world, and for exchanging
178data between Gall agents. When data comes in from a remote ship, destined for a
180data between Gall agents. When data comes in from a remote ship, destined for a
179−particular Gall agent, it will be validated by the local mark file in `/mar`
181+particular Gall agent, it will be validated by the mark file in `/mar` that
180−which corresponds to its `mark` before being delivered to the agent. If the
182+corresponds to its `mark` before being delivered to the agent. If the remote
181−remote data has no corresponding mark in `/mar` or it fails validation, it will
183+data has no corresponding mark in `/mar` or it fails validation, it will crash
182−crash before it touches the agent.
184+before it touches the agent.
184−A mark file is a `door` with three arms. The door's sample is the data type that
186+A mark file is a `door` with three arms. The door's sample is the data type the
185−particular mark will handle. For example, the sample of the `%noun` mark is just
187+mark will handle. For example, the sample of the `%noun` mark is just `non=*`,
186−`non=*`, since it handles any noun. The three arms are as follows:
188+since it handles any noun. The three arms are as follows:
188- `grab`: Methods for converting _to_ our mark _from_ other marks.
190- `grab`: Methods for converting _to_ our mark _from_ other marks.
189- `grow`: Methods for converting _from_ our mark _to_ other marks.
191- `grow`: Methods for converting _from_ our mark _to_ other marks.
@@ -192,16 +194,16 @@ particular mark will handle. For example, the sample of the `%noun` mark is just
192In the context of Gall agents, you'll likely just use marks for sending and
194In the context of Gall agents, you'll likely just use marks for sending and
193receiving data, and not for actually storing files in Clay. Therefore, it's
195receiving data, and not for actually storing files in Clay. Therefore, it's
194unlikely you'll need to write custom revision control functions in the `grad`
196unlikely you'll need to write custom revision control functions in the `grad`
195−arm for marks you use in your agent. Instead, you can simply delegate `grad`
197+arm. Instead, you can simply delegate `grad` functions to another mark -
196−functions to another mark - typically `%noun`. If you want to learn more about
198+typically `%noun`. If you want to learn more about writing such `grad`
197−writing such `grad` functions, you can refer to the [Marks
199+functions, you can refer to the [Marks Guide](/docs/arvo/clay/marks/marks) in
198−Guide](/docs/arvo/clay/marks/marks) in the Clay vane documentation, which is
200+the Clay vane documentation, which is much more comprehensive, but it's not
199−much more comprehensive, but it's not necessary for our purposes here.
201+necessary for our purposes here.
201#### Example
203#### Example
203Here's a very simple mark file for the `action` structure we created in the
205Here's a very simple mark file for the `action` structure we created in the
204−[previous section](sur):
206+[previous section](#sur):
@@ -231,10 +233,10 @@ it will handle. Now let's consider the arms:
231- `grow`: This handles conversion methods _from_ our mark. Like `grab`, it
233- `grow`: This handles conversion methods _from_ our mark. Like `grab`, it
232 contains a core with arm names corresponding to other marks. Here we've also
234 contains a core with arm names corresponding to other marks. Here we've also
233 only added an arm for a `%noun` mark. In this case, `action` data will come in
235 only added an arm for a `%noun` mark. In this case, `action` data will come in
234− as the sample of our `door`, and the `noun` arm simply returns its, since it's
236+ as the sample of our `door`, and the `noun` arm simply returns it, since it's
235 already a noun (as everything is in Hoon).
237 already a noun (as everything is in Hoon).
236- `grad`: This is the revision control arm, and as you can see we've simply
238- `grad`: This is the revision control arm, and as you can see we've simply
237− delegated such functions to the `%noun` mark.
239+ delegated it to the `%noun` mark.
239This mark file could be saved as `/mar/todo/action.hoon`, and then the `on-poke`
241This mark file could be saved as `/mar/todo/action.hoon`, and then the `on-poke`
240arm in the previous example could test for it instead of `%noun` like so:
242arm in the previous example could test for it instead of `%noun` like so:
@@ -249,7 +251,7 @@ arm in the previous example could test for it instead of `%noun` like so:
251Note how `%todo-action` will be resolved to `/mar/todo/action.hoon` - the hyphen
253Note how `%todo-action` will be resolved to `/mar/todo/action.hoon` - the hyphen
252−will be interpreted as `/` if there's not already `/mar/todo-action.hoon`.
254+will be interpreted as `/` if there's not already a `/mar/todo-action.hoon`.
254This simple mark file isn't all that useful. Typically, you'd add `json` arms to
256This simple mark file isn't all that useful. Typically, you'd add `json` arms to
255`grow` and `grab`, which allow your data to be converted to and from JSON, and
257`grow` and `grab`, which allow your data to be converted to and from JSON, and
@@ -270,10 +272,9 @@ pokes are actually coming from - our example agents would accept data from
270anywhere, including random foreign ships. We'll now have a look at how to handle
272anywhere, including random foreign ships. We'll now have a look at how to handle
271such permission checks.
273such permission checks.
273−The `bowl` provided as the sample of an agent core includes a couple of useful
275+The `bowl` includes a couple of useful fields: `our` and `src`. The `our` field
274−fields: `our` and `src`. The `our` field just contains the `@p` of the local
276+just contains the `@p` of the local ship. The `src` field contains the `@p` of
275−ship. The `src` field contains the `@p` of the ship from which the event
277+the ship from which the event originated.
278When messages come in over Ames from other ships on the network, they're
279When messages come in over Ames from other ships on the network, they're
279encrypted with our ship's public keys and signed by the ship which sent them.
280encrypted with our ship's public keys and signed by the ship which sent them.
@@ -338,7 +339,8 @@ Mark files:
338- A `mark` like `%foo` corresponds to a file in `/mar` like `/mar/foo.hoon`
339- A `mark` like `%foo` corresponds to a file in `/mar` like `/mar/foo.hoon`
339- Marks are file types in Clay, but are also used for passing data between
340- Marks are file types in Clay, but are also used for passing data between
340 agents as well as for external data generally.
341 agents as well as for external data generally.
341−- A mark file is a `door` with a sample of the data type it handles and three arms: `grab`, `grow` and `grad`.
342+- A mark file is a `door` with a sample of the data type it handles and three
343+ arms: `grab`, `grow` and `grad`.
342- `grab` and `grow` each contain a core with arm names corresponding to other marks.
344- `grab` and `grow` each contain a core with arm names corresponding to other marks.
343- `grab` and `grow` define functions for converting to and from our mark,
345- `grab` and `grow` define functions for converting to and from our mark,
344 respectively.
346 respectively.