Clay is a typed filesystem, and we call these file types
marks. When talking about Hoon and Arvo we'll often talk of types like
(list @t), etc. A
mark will specify such a type for its files, but it does more than just that - it also defines conversion routines to and from other
marks, as well as diff, patch, and merge routines.
For example, a
mark defines the type of a
%txt file as a
(list @t)). It defines a conversion function to a
mark to allow it to be serialized and sent to a browser or to the Unix filesystem. It also includes Hunt-McIlroy diff, patch, and merge algorithms. Conversion functions will be different for different
marks, as will things like diff algorithms. An image file like a
%png, for example, just replaces the old blob of data with the new one rather than implementing a complex binary diff and patch algorithm, so how these functions are implemented depends on the file type and use case.
mark files are stored in the
/mar directory. The
path of the
mark, for example, is
mark is a door (a core with a sample) with three arms:
+grad. The door's sample defines its type. In
+grab is a series of functions to convert from other
marks to the given
+grow is a series of functions to convert from the given
mark to other
Here's its basic structure in an informal pseudocode:
|_ <mark-type> ++ grab: ++ noun: <noun> -> <mark-type> ++ mime: <mime> -> <mark-type> ++ txt: <txt> -> <mark-type> ... ++ grow: ++ noun: <mark-type> -> <noun> ++ mime: <mark-type> -> <mime> ++ txt: <mark-type> -> <txt> ... ++ grad ++ form: <diff-mark> ++ diff: (<mark-type>, <mark-type>) -> <diff-type> ++ pact: (<mark-type>, <diff-type>) -> <mark-type> ++ join: (<diff-type>, <diff-type>) -> <diff-type> or NULL ++ mash: (<diff-type>, <diff-type>) -> <diff-type>
These types are basically what you would expect. In
+grab, only a
+noun arm is mandatory, the rest are optional. The
+grow arm itself is optional, as are any arms within it. In
+grad, all arms are mandatory unless revision control is delegated to another
mark, which we'll discuss later.
In general, for a particular
+grow entries should be inverses of each other. They needn't be symmetrical though - you may want to be able to convert from your
%json but not from
%json to your
mark, for example.
+diff takes two instances of a
mark and produces a diff of them whose
mark is given by
+pact takes an instance of a
mark and patches it with the given diff. In general, if
+diff called with A and B produces diff D, then
+pact called with A and D should produce B.
+join takes two diffs and attempts to merge them into a single diff. If there are conflicts, it produces null.
+mash takes two diffs and forces a merge, even if there are conflicts. How your
+mash function force-merges conflicting diffs is up to you. The
mark annotates any conflicts, for example, but there may be other ways. If
+join of two diffs does not produce null, then
+mash of the same diffs should produce the same result. Note that
+mash is not used by Clay in its ordinary filesystem operations, so you may wish to leave it as a dummy arm that crashes if called.
Alternately, instead of
mark can provide the same functionality by defining
+grad to be the name of another
mark to which we wish to delegate the revision control responsibilities. Then, before running any of those functions, Clay will convert to the other
mark, and convert back afterward. For example, the
mark is revision-controlled in the same way as
%txt, so its
+grad is simply
++ grad %txt. Of course,
+txt must be defined in
+grab as well.
We mentioned that
+noun is the only mandatory arm in
+grab, but there are a couple of others that, while not mandatory, are of particular interest.
The first is a
+mime arm for converting to and from the
mark. When you
|commit a file to a
desk mounted to Unix, Clay will receive the data as a
mark, and then convert it to the
mark matching the file extension. It will perform the same operation in reverse when mounting a
desk to Unix. For this reason, any
mark you wish to be able to access from the Unix filesystem should have
%mime conversion routines. In certain cases (such as the scry interface), Eyre will also need to convert your
mark to a
%mime in order to encode it in an HTTP response, so you may require a
+mime arm for that reason as well.
The second case of interest is the
+json arm for converting to and from a
mark. If, for example, you want to write a Gall agent to which you can subscribe through Eyre's channel system, it must produce data with a
%json conversion routines. If it doesn't, Eyre will not be able to deliver the data to the subscribed HTTP client in the SSE stream.
Writing Marks - A practical walk-through of writing a
Using Marks - Details of using
mark conversion gates and
mark cores in your own code.
Examples - The example code used in the Writing Marks guide.