@@ -7,7 +7,7 @@ template = "doc.html"
9- [Introduction](#introduction)
9- [Introduction](#introduction)
10−- [Read and Subscribe](#read-and-subscribe)
10+- [%warp](#warp) - Read and Subscribe.
11 - [%sing](#sing) - Read a file or directory.
11 - [%sing](#sing) - Read a file or directory.
12 - [%next](#next) - Subscribe for the next change to a file or directory.
12 - [%next](#next) - Subscribe for the next change to a file or directory.
13 - [%mult](#mult) - Subscribe for the next change to a set of files and/or directories.
13 - [%mult](#mult) - Subscribe for the next change to a set of files and/or directories.
@@ -28,8 +28,8 @@ template = "doc.html"
28 - [%crew](#crew) - Get permission groups.
28 - [%crew](#crew) - Get permission groups.
29 - [%crow](#crow) - Get group usage.
29 - [%crow](#crow) - Get group usage.
30- [Foreign Ships](#foreign-ships)
30- [Foreign Ships](#foreign-ships)
31− - [%warp](#warp) - Read a file on a foreign ship.
31+ - [%warp](#warp-remote) - Read a file on a foreign ship.
32− - [%merg](#merg) - Merge from a foreign `desk`.
32+ - [%merg](#merg-remote) - Merge from a foreign `desk`.
34# Introduction
34# Introduction
@@ -37,14 +37,16 @@ This document details all the `task`s you're likely to use to interact with Clay
38The focus of this document is on interacting with Clay from userspace applications and threads, so it doesn't delve into the internal mechanics of Clay from a kernel development perspective.
38The focus of this document is on interacting with Clay from userspace applications and threads, so it doesn't delve into the internal mechanics of Clay from a kernel development perspective.
40−# Read and Subscribe
40+# `%warp`
42−Here we'll look at reading files and subscribing to changes. This is done by sending Clay a `%warp` `task`:
45[%warp wer=ship rif=riff] :: internal file req
43[%warp wer=ship rif=riff] :: internal file req
46+A `%warp` `task` is for reading a subscribing to files and directories.
48The `wer` field is the target ship. The `(unit rave)` of the [riff](@/docs/arvo/clay/data-types.md#riff-clay-request-desist) is null to cancel an existing subscription, otherwise the [rave](@/docs/arvo/clay/data-types.md#rave-clay-general-subscription-request) is tagged with one of:
50The `wer` field is the target ship. The `(unit rave)` of the [riff](@/docs/arvo/clay/data-types.md#riff-clay-request-desist) is null to cancel an existing subscription, otherwise the [rave](@/docs/arvo/clay/data-types.md#rave-clay-general-subscription-request) is tagged with one of:
50- `%sing` - Read a single file or directory.
52- `%sing` - Read a single file or directory.
@@ -54,6 +56,8 @@ The `wer` field is the target ship. The `(unit rave)` of the [riff](@/docs/arvo/
55We'll look at each of these in more detail below.
57We'll look at each of these in more detail below.
57Clay responds to a `%mult` request with a `%wris` `gift`, and the rest with a `%writ` `gift`.
61Clay responds to a `%mult` request with a `%wris` `gift`, and the rest with a `%writ` `gift`.
59A `%wris` `gift` looks like:
63A `%wris` `gift` looks like:
@@ -72,19 +76,23 @@ The `unit` of the [riot](@/docs/arvo/clay/data-types.md#riot-clay-response) will
73Now we'll look at each of the `rave` request types in turn.
77Now we'll look at each of the `rave` request types in turn.
78[%sing =mood]
82[%sing =mood]
85+This `rave` is for reading a single file or directory immediately.
81−This is for reading a single file or directory immediately. The `care` of the [mood](@/docs/arvo/clay/data-types.md#mood-clay-single-subscription-request) will determine what you can read and what type of data will be returned. See the [care](@/docs/arvo/clay/data-types.md#care-clay-clay-submode) documentation and [scry](@/docs/arvo/clay/scry.md) documentation for details on the various `care`s.
87+The `care` of the [mood](@/docs/arvo/clay/data-types.md#mood-clay-single-subscription-request) will determine what you can read and what type of data will be returned. See the [care](@/docs/arvo/clay/data-types.md#care-clay-clay-submode) documentation and [scry](@/docs/arvo/clay/scry.md) documentation for details on the various `care`s.
83The [case](@/docs/arvo/clay/data-types.md#case-specifying-a-commit) specifies the `desk` revision and you can use whichever kind you prefer. The `path` will usually be a path to a file or directory like `/gen/hood/hi/hoon` but may be something else depending on the `care`.
89The [case](@/docs/arvo/clay/data-types.md#case-specifying-a-commit) specifies the `desk` revision and you can use whichever kind you prefer. The `path` will usually be a path to a file or directory like `/gen/hood/hi/hoon` but may be something else depending on the `care`.
85[See here for an example of using %sing.](@/docs/arvo/clay/examples.md#sing)
93[See here for an example of using %sing.](@/docs/arvo/clay/examples.md#sing)
90[%next =mood] :: await next version
98[%next =mood] :: await next version
@@ -94,9 +102,11 @@ This subscribes to the next version of the specified file. See [here](@/docs/arv
95If you subscribe to the current `case` of the `desk`, Clay will not respond until the file changes. If you subscribe to a previous `case` of the `desk` and the file has changed in between then and now, it will immediately return the first change it comes across in that range. For example, if you're currently at `case` `100`, subscribe to case `50` and the file in question has been modified at both `60` and `80`, clay will immediately return the version of the file at `case` `60`.
103If you subscribe to the current `case` of the `desk`, Clay will not respond until the file changes. If you subscribe to a previous `case` of the `desk` and the file has changed in between then and now, it will immediately return the first change it comes across in that range. For example, if you're currently at `case` `100`, subscribe to case `50` and the file in question has been modified at both `60` and `80`, clay will immediately return the version of the file at `case` `60`.
97[See here for an example of using %next.](@/docs/arvo/clay/examples.md#next)
107[See here for an example of using %next.](@/docs/arvo/clay/examples.md#next)
99−## %mult
109+## `%mult`
102[%mult =mool] :: next version of any
112[%mult =mool] :: next version of any
@@ -114,9 +124,11 @@ The `mool` specified in the request is this structure:
115You can use a different `care` for each of the files specified by the `path` if you like. Significantly, the `care` will determine whether Clay sends a response for a given change. For example, if you subscribe to an existing `/foo/txt` with a `%u` `care` and `/foo/txt` is modified but isn't deleted, Clay will *not* tell you. However, if you subscribe with an `%x` `care`, it *will* tell you.
125You can use a different `care` for each of the files specified by the `path` if you like. Significantly, the `care` will determine whether Clay sends a response for a given change. For example, if you subscribe to an existing `/foo/txt` with a `%u` `care` and `/foo/txt` is modified but isn't deleted, Clay will *not* tell you. However, if you subscribe with an `%x` `care`, it *will* tell you.
117[See here for an example of using %mult.](@/docs/arvo/clay/examples.md#mult)
129[See here for an example of using %mult.](@/docs/arvo/clay/examples.md#mult)
119−## %many
131+## `%many`
122[%many track=? =moat] :: track range
134[%many track=? =moat] :: track range
@@ -144,24 +156,30 @@ When you reach the end of the subscribed range of `case`s, Clay will send you a
144[%writ p=~]
156[%writ p=~]
147[See here for an example of using %many.](@/docs/arvo/clay/examples.md#many)
161[See here for an example of using %many.](@/docs/arvo/clay/examples.md#many)
149## Cancel Subscription
163## Cancel Subscription
151To cancel a subscription, you just send a `%warp` with a null `(unit rave)` in the `riff`. Clay will cancel the subscription based on the `wire`. The request is exactly the same regardless of which type of `rave` you subscribed with originally.
165To cancel a subscription, you just send a `%warp` with a null `(unit rave)` in the `riff`. Clay will cancel the subscription based on the `wire`. The request is exactly the same regardless of which type of `rave` you subscribed with originally.
153[See here for an example of cancelling a subscription.](@/docs/arvo/clay/examples.md#cancel-subscription)
169[See here for an example of cancelling a subscription.](@/docs/arvo/clay/examples.md#cancel-subscription)
155# Write and Modify
171# Write and Modify
157−## %info
173+## `%info`
159−To write or modify a file, we send Clay a `%info` `task`:
162[%info des=desk dit=nori] :: internal edit
176[%info des=desk dit=nori] :: internal edit
179+To write or modify a file, we send Clay a `%info` `task`.
165The `%|` tag in the [nori](@/docs/arvo/clay/data-types.md#nori-clay-repository-action) is not currently supported and will crash with a `%labelling-not-implemented` if used, so you can focus on the `%&` part. The [soba](@/docs/arvo/clay/data-types.md#soba-clay-delta) in the `nori` is just a list of changes so you can make more than one change in one request. Its `path` is just the path to a file like `/gen/hood/hi/hoon` and the [miso](@/docs/arvo/clay/data-types.md#miso-clay-ankh-delta) is one of these types of requests:
183The `%|` tag in the [nori](@/docs/arvo/clay/data-types.md#nori-clay-repository-action) is not currently supported and will crash with a `%labelling-not-implemented` if used, so you can focus on the `%&` part. The [soba](@/docs/arvo/clay/data-types.md#soba-clay-delta) in the `nori` is just a list of changes so you can make more than one change in one request. Its `path` is just the path to a file like `/gen/hood/hi/hoon` and the [miso](@/docs/arvo/clay/data-types.md#miso-clay-ankh-delta) is one of these types of requests:
167- `%del` - Delete a file.
185- `%del` - Delete a file.
@@ -169,8 +187,12 @@ The `%|` tag in the [nori](@/docs/arvo/clay/data-types.md#nori-clay-repository-a
169- `%dif` - This has not yet been implemented so will crash with a `%dif-not-implemented` error.
187- `%dif` - This has not yet been implemented so will crash with a `%dif-not-implemented` error.
170- `%mut` - Change a file. At the time of writing this behaves identically to `%ins` so its use merely informs the reader.
188- `%mut` - Change a file. At the time of writing this behaves identically to `%ins` so its use merely informs the reader.
172Clay does not give any response to an `%info` `task` so don't expect a `sign` back.
192Clay does not give any response to an `%info` `task` so don't expect a `sign` back.
174Here are examples of using each of these as well as making multiple changes in one request:
196Here are examples of using each of these as well as making multiple changes in one request:
176- [%del](@/docs/arvo/clay/examples.md#del)
198- [%del](@/docs/arvo/clay/examples.md#del)
@@ -190,15 +212,21 @@ There are four Clay `task`s relevant to mounts:
190- [%ogre](#ogre) - Unmount something.
212- [%ogre](#ogre) - Unmount something.
191- [%dirk](#dirk) - Commit changes.
213- [%dirk](#dirk) - Commit changes.
193−## %boat
215+## `%boat`
195−This type of `task` will request the list of existing mounts. It looks like:
221+A `%boat` `task` requests the list of existing mounts.
225+A `%boat` `task` does not take any arguments.
201−Pretty simple. The type it returns is a `%hill` `gift`, which looks like:
229+The type it returns is a `%hill` `gift`, which looks like:
204[%hill p=(list @tas)]
232[%hill p=(list @tas)]
@@ -206,16 +234,20 @@ Pretty simple. The type it returns is a `%hill` `gift`, which looks like:
207...where the `@tas` is the name of the mount point.
235...where the `@tas` is the name of the mount point.
209−[See here for an example of using %boat.](@/docs/arvo/clay/examples.md#boat)
237+### Example
211−## %mont
239+[See here for an example of using %boat.](@/docs/arvo/clay/examples.md#boat)
213−This type of `task` mounts the specified `beam` to the specified `term` mount point. It looks like:
241+## `%mont`
216[%mont pot=term bem=beam]
244[%mont pot=term bem=beam]
247+A `%mont` `task` mounts the specified `beam` to the specified `term` mount point.
219A `beam:clay` is the following structure:
251A `beam:clay` is the following structure:
@@ -224,37 +256,57 @@ A `beam:clay` is the following structure:
225You can mount the whole desk with a `path` of `/`, and you can also mount subdirectories or even individual files. If you want to mount an individual file, you must exclude its `mark` from the path. For example, if you want to mount `/gen/hood/hi/hoon`, you'd specify `/gen/hood/hi`. It will automatically be given the correct file extension when mounted. If you include the `hoon` mark it will crash (and currently crash your ship).
257You can mount the whole desk with a `path` of `/`, and you can also mount subdirectories or even individual files. If you want to mount an individual file, you must exclude its `mark` from the path. For example, if you want to mount `/gen/hood/hi/hoon`, you'd specify `/gen/hood/hi`. It will automatically be given the correct file extension when mounted. If you include the `hoon` mark it will crash (and currently crash your ship).
227−[See here for an example of using %mont.](@/docs/arvo/clay/examples.md#mont)
259+### Returns
261+Clay does not return a `gift` in response to a `%mont` `%task`.
229−## %ogre
263+### Example
265+[See here for an example of using %mont.](@/docs/arvo/clay/examples.md#mont)
231−This type of `task` unmounts the specified mount. It's defined in `lull.hoon` as:
267+## `%ogre`
234[%ogre pot=$@(desk beam)]
270[%ogre pot=$@(desk beam)]
237−But in fact it will only unmount the target when specified as a `term` mount name. Passing it a `desk` will incidentally work if the mount is named the same as the `desk` but otherwise it won't work. Passing it a `beam:clay` will simply not work.
273+A `%ogre` `task` unmounts the specified mount.
239−[See here for an example of using %ogre.](@/docs/arvo/clay/examples.md#ogre)
275+### Accepts
277+It's defined in `lull.hoon` as taking `$@(desk beam)` but in fact it will only unmount the target when specified as a `term` mount name. Passing it a `desk` will incidentally work if the mount is named the same as the `desk` but otherwise it won't work. Passing it a `beam:clay` will simply not work.
241−## %dirk
281+Clay does not return a `gift` in response to a `%ogre` `task`.
243−This type of `task` commits changes in the target mount. It's defined in `lull.hoon` as:
283+### Example
285+[See here for an example of using %ogre.](@/docs/arvo/clay/examples.md#ogre)
246[%dirk des=desk]
290[%dirk des=desk]
295+A `%dirk` `task` commits changes in the target mount.
249−... but like [%ogre](#ogre), it actually takes the name of a mount point rather than a `desk` as is specified.
297+It's defined in `lull.hoon` as taking a `desk` but like [%ogre](#ogre), it actually takes the name of a mount point rather than a `desk` as is specified.
301+Clay does not return a `gift` in response to a `%dirk` `task`.
251[See here for an example of using %dirk.](@/docs/arvo/clay/examples.md#dirk)
305[See here for an example of using %dirk.](@/docs/arvo/clay/examples.md#dirk)
253# Merge Desks
307# Merge Desks
255−## %merg
309+## `%merg`
257−A `%merg` `task` will merge the specified source `desk` into the target local `desk`. It looks like:
260$: %merg :: merge desks
312$: %merg :: merge desks
@@ -264,10 +316,16 @@ $: %merg :: merge desks
319+A `%merg` `task` will merge the specified source `desk` into the target local `desk`.
267The `germ` specifies the merge strategy. You can refer to the [Strategies](@/docs/arvo/clay/using.md#strategies) section of the [Using Clay](@/docs/arvo/clay/using.md) document for details of each `germ`.
323The `germ` specifies the merge strategy. You can refer to the [Strategies](@/docs/arvo/clay/using.md#strategies) section of the [Using Clay](@/docs/arvo/clay/using.md) document for details of each `germ`.
269If you're merging into a new `desk` you must use `%init`, all other strategies will fail. If the desk already exists, you cannot use `%init`. Otherwise, you're free to use whichever you'd like.
325If you're merging into a new `desk` you must use `%init`, all other strategies will fail. If the desk already exists, you cannot use `%init`. Otherwise, you're free to use whichever you'd like.
271Clay will respond to the request with a `%mere` `gift` which looks like:
329Clay will respond to the request with a `%mere` `gift` which looks like:
@@ -287,6 +345,8 @@ If the merge failed, `p` will have a head of `%.n` and then a `[term tang]` wher
290[See here for an example of using %merg.](@/docs/arvo/clay/examples.md#merg)
350[See here for an example of using %merg.](@/docs/arvo/clay/examples.md#merg)
292# Permissions
352# Permissions
@@ -331,18 +391,18 @@ A `%perm` `task` is for setting permissions, and the other three are for managin
332We'll look at each of these in turn.
392We'll look at each of these in turn.
334−## %perm
394+## `%perm`
336−This sets permissions for the target file or directory.
338−Note this will replace existing permissions rather than add to them, so if you want to add a ship to an existing whitelist or whatever you'll have to first read the existing permissions, add the ship, then send the whole lot back.
340−A `%perm` `task` looks like:
343[%perm des=desk pax=path rit=rite] :: change permissions
397[%perm des=desk pax=path rit=rite] :: change permissions
400+A `%perm` `task` sets permissions for the target file or directory.
402+Note this will replace existing permissions rather than add to them, so if you want to add a ship to an existing whitelist or whatever you'll have to first read the existing permissions, add the ship, then send the whole lot back.
346The `pax` path is the file or directory whose permissions you want to change, and the `rite` is this structure:
406The `pax` path is the file or directory whose permissions you want to change, and the `rite` is this structure:
@@ -366,33 +426,52 @@ Where a `rule` is this structure:
367As the comment suggests, the `@ta` is the name of a `crew` (group).
427As the comment suggests, the `@ta` is the name of a `crew` (group).
369−[See here for an example of using %perm.](@/docs/arvo/clay/examples.md#perm)
429+### Returns
431+Clay does not return a `gift` in response to a `%perm` `task`.
371−## %cred
433+### Example
435+[See here for an example of using %perm.](@/docs/arvo/clay/examples.md#perm)
373−This simply creates a permission group. The task looks like this:
437+## `%cred`
376[%cred nom=@ta cew=crew] :: set permission group
440[%cred nom=@ta cew=crew] :: set permission group
443+This simply creates a permission group.
379The `nom` is a name for the group and the `crew` is just a `(set ship)`:
447The `nom` is a name for the group and the `crew` is just a `(set ship)`:
382+$ crew (set ship) :: permissions group
450+$ crew (set ship) :: permissions group
385−[See here for an example of using %cred.](@/docs/arvo/clay/examples.md#cred)
453+### Returns
387−## %crew
455+Clay does not return a `gift` in response to a `%cred` `task`.
389−This retrieves all permission groups. It looks like:
457+### Example
459+[See here for an example of using %cred.](@/docs/arvo/clay/examples.md#cred)
392[%crew ~] :: permission groups
464[%crew ~] :: permission groups
466+This retrieves all permission groups.
470+A `%crew` `task` takes no arguments.
395−Clay wil return a sign containing a `%cruz` `gift`. It looks like:
474+Clay wil return a `%cruz` `gift`. It looks like:
398[%cruz cez=(map @ta crew)] :: permission groups
477[%cruz cez=(map @ta crew)] :: permission groups
@@ -400,16 +479,24 @@ Clay wil return a sign containing a `%cruz` `gift`. It looks like:
401The `cez` is just a map from group name to `crew` which is just a `(set ship)`.
480The `cez` is just a map from group name to `crew` which is just a `(set ship)`.
403−[See here for an example of using %crew.](@/docs/arvo/clay/examples.md#crew)
482+### Example
405−## %crow
484+[See here for an example of using %crew.](@/docs/arvo/clay/examples.md#crew)
407−This is the last group `task`. It retrieves all files and directories in all `desk`s which have permissions set for the group in question. It will not return inherited permissions, only those explicitly set. It looks like:
486+## `%crow`
410[%crow nom=@ta] :: group usage
489[%crow nom=@ta] :: group usage
492+A `%crow` `task` retrieves all files and directories in all `desk`s which have permissions set for the group in question. It will not return inherited permissions, only those explicitly set.
496+The `nom` is the name of a `crew`.
413The `gift` you get back is a `%croz` which looks like:
500The `gift` you get back is a `%croz` which looks like:
@@ -422,6 +509,8 @@ The `gift` you get back is a `%croz` which looks like:
422+$ regs (map path rule) :: rules for paths
509+$ regs (map path rule) :: rules for paths
425[See here for an example of using %crow.](@/docs/arvo/clay/examples.md#crow)
514[See here for an example of using %crow.](@/docs/arvo/clay/examples.md#crow)
427# Foreign Ships
516# Foreign Ships
@@ -430,9 +519,9 @@ Here we'll looking at making Clay requests to a foreign ship.
431As it currently stands, it's not possible to write to a foreign `desk`. Additionally, remote scries are not implemented. That leaves requests to read files (`%warp`) and merge desks (`%merg`), which we'll look at next.
520As it currently stands, it's not possible to write to a foreign `desk`. Additionally, remote scries are not implemented. That leaves requests to read files (`%warp`) and merge desks (`%merg`), which we'll look at next.
433−## %warp
522+## `%warp` - Remote
435−To read files on a foreign `desk`, you just send Clay a `%warp` `task` (as you would for a local read) and specify the target ship in the `wer` field. For details on making such requests, see the [Read and Subscribe](#read-and-subscribe) section.
524+To read files on a foreign `desk`, you just send Clay a `%warp` `task` (as you would for a local read) and specify the target ship in the `wer` field. For details on making such requests, see the [Read and Subscribe](#warp) section.
437Clay only allows a subset of `care`s to be used remotely. They are:
526Clay only allows a subset of `care`s to be used remotely. They are:
@@ -449,9 +538,11 @@ The foreign ship will respond only if correct permissions have been set. See the
450Note that if you're reading a whole `desk` or directory, all subfolders and files must also permit reading. If even a single file does not permit you reading it, the foreign ship will not respond to the request.
539Note that if you're reading a whole `desk` or directory, all subfolders and files must also permit reading. If even a single file does not permit you reading it, the foreign ship will not respond to the request.
452[See here for examples of requests to foreign ships.](@/docs/arvo/clay/examples.md#foreign-ships)
543[See here for examples of requests to foreign ships.](@/docs/arvo/clay/examples.md#foreign-ships)
454−## %merg
545+## `%merg` - Remote
456To merge a foreign `desk` into a local one, you just send Clay a `%merg` `task` (as you would for a local merge) and specify the foreign ship in the `her` field. For details on making such requests, see the [Merge Desks](#merge-desks) section.
547To merge a foreign `desk` into a local one, you just send Clay a `%merg` `task` (as you would for a local merge) and specify the foreign ship in the `her` field. For details on making such requests, see the [Merge Desks](#merge-desks) section.
@@ -459,4 +550,6 @@ The foreign ship will respond only if correct permissions have been set. See the
460Note that all subfolders and individual files within the `desk` must permit your reading in order for the merge to succeed. If even one file does not permit you reading it, the remote ship will not respond to the request at all.
551Note that all subfolders and individual files within the `desk` must permit your reading in order for the merge to succeed. If even one file does not permit you reading it, the remote ship will not respond to the request at all.
462[See here for examples of requests to foreign ships.](@/docs/arvo/clay/examples.md#foreign-ships)
555[See here for examples of requests to foreign ships.](@/docs/arvo/clay/examples.md#foreign-ships)