git.iko.soy/urbit.org
on c8ea9f2 help sign in
urbit.org/content/docs/userspace/full-stack/5-marks.md
97 lines 3.6 kB history raw
1+++
2title = "5. Marks"
3weight = 5
4template = "doc.html"
5+++
7In this section we'll write the mark files for our agent. We'll need two marks,
8one for poke `$action`s and one for subscription updates and scry results, both
9of which are `$update`s. Our `$action` mark will be called `%journal-action` and
10our `$update` mark will be called `%journal-update`. These will be located at
11`/mar/journal/action.hoon` and `/mar/journal/update.hoon`.
13Note that a mark called `%foo-bar` will first be looked for in
14`/mar/foo-bar.hoon`, and if it's not there it will be looked for in
15`/mar/foo/bar.hoon`. That's why we can have a single name like `%journal-action`
16but have it in `/mar/journal/action.hoon`
18## `%journal-action`
20```hoon
21/- *journal
22/+ *journal
23|_ act=action
24++ grow
25 |%
26 ++ noun act
27 --
28++ grab
29 |%
30 ++ noun action
31 ++ json dejs-action
32 --
33++ grad %noun
34--
35```
37First we import our `/sur/journal.hoon` structure file and also our
38`/lib/journal.hoon` library (containing our `$json` conversion functions). The
39sample of our mark door is just our `$action` structure. The `++grow` arm of a
40mark core, if you recall, contains methods for converting _from_ our mark _to_
41another mark. Actions only ever come inwards in pokes, so we don't need to worry
42about converting an `$action` _to_ `$json`. The `++grow` arm can therefore just
43handle the generic `%noun` case, simply returning our mark door's sample without
44doing anything.
46`++grab`, conversely, defines methods for converting _to_ our mark _from_
47another mark. Since `$action`s will come in from the front-end as `$json`, we
48need to be able to convert `$json` data to our `$action` structure. Our
49`/lib/journal.hoon` library contains the `++dejs-action` function for performing
50this conversion, so we can just specify that function for the `%json` case.
51We'll also define a standard `%noun` method, which will just "clam" (or "mold")
52the incoming noun with the `$action` mold. Clamming/molding coerces a noun to a
53type and is done by calling a mold as a function.
55Lastly, `++grad` defines revision control methods, but can be delegated to
56another mark. Since this mark will never be used for actually storing files in
57Clay, we can just delegate it to the generic `%noun` mark rather than writing a
58proper set of `++grad` methods.
60## `%journal-update`
62```hoon
63/- *journal
64/+ *journal
65|_ upd=update
66++ grow
67 |%
68 ++ noun upd
69 ++ json (enjs-update upd)
70 --
71++ grab
72 |%
73 ++ noun update
74 --
75++ grad %noun
76--
77```
79Next we have our `%journal-update` mark file. The sample of our mark door is our
80`$update` structure. Our `$update`s are always outbound, never inbound, so we
81only need to define a method for converting our `$update` structure to `$json`
82in the `++grow` arm, and not the opposite direction in `++grad`. Our
83`/lib/journal.hoon` library contains the `++enjs-update` function for performing
84this conversion, so we can call it with the sample `$update` as its argument. We
85can add `%noun` conversion methods and delegate revision control to the `%noun`
86mark in the same manner as our `%journal-action` mark above.
88## Resources
90- [The Marks section of the Clay documentation](/docs/arvo/clay/marks/marks) -
91 This section of the Clay vane documentation covers mark files comprehensively.
92- [The mark file section of the Gall
93 Guide](/docs/userspace/gall-guide/7-sur-and-marks#mark-files) - This part of
94 the Gall Guide goes through the basics of mark files.
96- [The JSON Guide](/docs/hoon/guides/json-guide) - This also covers writing mark
97 files to convert to/from JSON.