# 4. Marks

In this section we'll write the mark files for our agent. We'll need two marks, one for poke `$action`s and one for subscription updates and scry results, both of which are `$update`s. Our `$action` mark will be called `%journal-action` and our `$update` mark will be called `%journal-update`. These will be located at `/mar/journal/action.hoon` and `/mar/journal/update.hoon`.

Note that a mark called `%foo-bar` will first be looked for in `/mar/foo-bar.hoon`, and if it's not there it will be looked for in `/mar/foo/bar.hoon`. That's why we can have a single name like `%journal-action` but have it in `/mar/journal/action.hoon`

## `%journal-action` <a href="#journal-action" id="journal-action"></a>

```hoon
/-  *journal
/+  *journal
|_  act=action
++  grow
  |%
  ++  noun  act
  --
++  grab
  |%
  ++  noun  action
  ++  json  dejs-action
  --
++  grad  %noun
--
```

First we import our `/sur/journal.hoon` structure file and also our `/lib/journal.hoon` library (containing our `$json` conversion functions). The sample of our mark door is just our `$action` structure. The `+grow` arm of a mark core, if you recall, contains methods for converting *from* our mark *to* another mark. Actions only ever come inwards in pokes, so we don't need to worry about converting an `$action` *to* `$json`. The `+grow` arm can therefore just handle the generic `%noun` case, simply returning our mark door's sample without doing anything.

`+grab`, conversely, defines methods for converting *to* our mark *from* another mark. Since `$action`s will come in from the front-end as `$json`, we need to be able to convert `$json` data to our `$action` structure. Our `/lib/journal.hoon` library contains the `+dejs-action` function for performing this conversion, so we can just specify that function for the `%json` case. We'll also define a standard `%noun` method, which will just "clam" the incoming noun with the `$action` mold. Clamming/molding coerces a noun to a type and is done by calling a mold as a function.

Lastly, `+grad` defines revision control methods, but can be delegated to another mark. Since this mark will never be used for actually storing files in Clay, we can just delegate it to the generic `%noun` mark rather than writing a proper set of `+grad` methods.

## `%journal-update` <a href="#journal-update" id="journal-update"></a>

```hoon
/-  *journal
/+  *journal
|_  upd=update
++  grow
  |%
  ++  noun  upd
  ++  json  (enjs-update upd)
  --
++  grab
  |%
  ++  noun  update
  --
++  grad  %noun
--
```

Next we have our `%journal-update` mark file. The sample of our mark door is our `$update` structure. Our `$update`s are always outbound, never inbound, so we only need to define a method for converting our `$update` structure to `$json` in the `+grow` arm, and not the opposite direction in `+grad`. Our `/lib/journal.hoon` library contains the `+enjs-update` function for performing this conversion, so we can call it with the sample `$update` as its argument. We can add `%noun` conversion methods and delegate revision control to the `%noun` mark in the same manner as our `%journal-action` mark above.

## Resources <a href="#resources" id="resources"></a>

* [The Marks section of the Clay documentation](https://docs.urbit.org/urbit-os/kernel/clay/marks) - This section of the Clay vane documentation covers mark files comprehensively.
* [The mark file section of the Gall Guide](https://docs.urbit.org/app-school/7-sur-and-marks#mark-files) - This part of App School goes through the basics of mark files.
* [The JSON Guide](https://docs.urbit.org/hoon/json-guide) - This also covers writing mark files to convert to/from JSON.