@@ -4,49 +4,18 @@ weight = 6
4template = "doc.html"
4template = "doc.html"
9−- [Introduction](#introduction)
10−- [%warp](#warp) - Read and Subscribe.
11− - [%sing](#sing) - Read 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.
14− - [%many](#many) - Track changes to a `desk` for the specified range of revisions.
15− - [Cancel Subscription](#cancel-subscription)
16−- [Write and Modify](#write-and-modify)
18−- [Manage Mounts](#manage-mounts)
19− - [%boat](#boat) - List mounts.
20− - [%mont](#mont) - Mount something.
21− - [%ogre](#ogre) - Unmount something.
22− - [%dirk](#dirk) - Commit changes.
23−- [Merge Desks](#merge-desks)
25−- [Permissions](#permissions)
26− - [%perm](#perm) - Set file permissions.
27− - [%cred](#cred) - Add permission group.
28− - [%crew](#crew) - Get permission groups.
29− - [%crow](#crow) - Get group usage.
30−- [Foreign Ships](#foreign-ships)
31− - [%warp](#warp-remote) - Read a file on a foreign ship.
32− - [%merg](#merg-remote) - Merge from a foreign `desk`.
36This document details all the `task`s you're likely to use to interact with Clay, as well as the `gift`s you'll receive in response. Each section has a corresponding practical example in the [Examples](/docs/arvo/clay/examples) document. Many of the types referenced are detailed in the [Data Types](/docs/arvo/clay/data-types) document. It may also be useful to look at the `++ clay` section of `/sys/lull.hoon` in Arvo where these `task`s, `gift`s and data structures are defined.
7This document details all the `task`s you're likely to use to interact with Clay, as well as the `gift`s you'll receive in response. Each section has a corresponding practical example in the [Examples](/docs/arvo/clay/examples) document. Many of the types referenced are detailed in the [Data Types](/docs/arvo/clay/data-types) document. It may also be useful to look at the `++ clay` section of `/sys/lull.hoon` in Arvo where these `task`s, `gift`s and data structures are defined.
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.
9The 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−# `%warp`
11+## `%warp` - Read and track
42−A `%warp` `task` is for reading a subscribing to files and directories.
47−[wer=ship rif=riff]
14+[%warp wer=ship rif=riff]
17+A `%warp` `task` is for reading and subscribing to files and directories.
50The `wer` field is the target ship. The `(unit rave)` of the [riff](/docs/arvo/clay/data-types#riff-clay-request-desist) is null to cancel an existing subscription, otherwise the [rave](/docs/arvo/clay/data-types#rave-clay-general-subscription-request) is tagged with one of:
19The `wer` field is the target ship. The `(unit rave)` of the [riff](/docs/arvo/clay/data-types#riff-clay-request-desist) is null to cancel an existing subscription, otherwise the [rave](/docs/arvo/clay/data-types#rave-clay-general-subscription-request) is tagged with one of:
52- `%sing` - Read a single file or directory.
21- `%sing` - Read a single file or directory.
@@ -56,7 +25,7 @@ The `wer` field is the target ship. The `(unit rave)` of the [riff](/docs/arvo/c
57We'll look at each of these in more detail below.
26We'll look at each of these in more detail below.
59−### Returns
28+#### Returns
61Clay responds to a `%mult` request with a `%wris` `gift`, and the rest with a `%writ` `gift`.
30Clay responds to a `%mult` request with a `%wris` `gift`, and the rest with a `%writ` `gift`.
@@ -76,7 +45,7 @@ The `unit` of the [riot](/docs/arvo/clay/data-types#riot-clay-response) will be
77Now we'll look at each of the `rave` request types in turn.
46Now we'll look at each of the `rave` request types in turn.
79−## `%sing`
48+### `%sing` - Read
82[%sing =mood]
51[%sing =mood]
@@ -88,11 +57,11 @@ The `care` of the [mood](/docs/arvo/clay/data-types#mood-clay-single-subscriptio
89The [case](/docs/arvo/clay/data-types#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`.
58The [case](/docs/arvo/clay/data-types#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`.
91−### Example
60+#### Example
93[See here for an example of using %sing.](/docs/arvo/clay/examples#sing)
62[See here for an example of using %sing.](/docs/arvo/clay/examples#sing)
95−## `%next`
64+### `%next` - Await next
98[%next =mood] :: await next version
67[%next =mood] :: await next version
@@ -102,19 +71,19 @@ This subscribes to the next version of the specified file. See [here](/docs/arvo
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`.
72If 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`.
105−### Example
74+#### Example
107[See here for an example of using %next.](/docs/arvo/clay/examples#next)
76[See here for an example of using %next.](/docs/arvo/clay/examples#next)
109−## `%mult`
78+### `%mult` - Next of any
112−[%mult =mool] :: next version of any
81+[%mult =mool]
115−This subscribes to the next version of a `set` of files or directories. Clay will only send a single response, and it will send it when *any* of the specified files change. For example, if you subscribe to both `/foo/txt` and `/bar/txt`, and only `/foo/txt` changes, Clay will send a response indicating a change to `/foo/txt`. If `/bar/txt` changes subsequently, it will not tell you. If more than one file changes at once, it will tell you about each of the changes in the one response.
84+This subscribes to the next version of a `set` of files or directories. Clay will only send a single response, and it will send it when _any_ of the specified files change. For example, if you subscribe to both `/foo/txt` and `/bar/txt`, and only `/foo/txt` changes, Clay will send a response indicating a change to `/foo/txt`. If `/bar/txt` changes subsequently, it will not tell you. If more than one file changes at once, it will tell you about each of the changes in the one response.
117−The behaviour with respect to requesting old `case`s is the same as explained in the [`%next`](#next) section above.
86+The behaviour with respect to requesting old `case`s is the same as explained in the [`%next`](#next---await-next) section above.
119The `mool` specified in the request is this structure:
88The `mool` specified in the request is this structure:
@@ -122,16 +91,16 @@ The `mool` specified in the request is this structure:
122+$ mool [=case paths=(set (pair care path))] :: requests in desk
91+$ mool [=case paths=(set (pair care path))] :: requests in desk
125−You 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.
94+You 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.
127−### Example
96+#### Example
129[See here for an example of using %mult.](/docs/arvo/clay/examples#mult)
98[See here for an example of using %mult.](/docs/arvo/clay/examples#mult)
131−## `%many`
100+### `%many` - Track range
134−[%many track=? =moat] :: track range
103+[%many track=? =moat]
137This subscribes to all changes to a `desk` for the specified range of `case`s. Note that you're unlikely to use this directly, it's mostly used implicitly if you make a `%sing` or `%next` request with a `%v` `care` to a foreign `desk`. Regardless, we'll have a look at it for completeness.
106This subscribes to all changes to a `desk` for the specified range of `case`s. Note that you're unlikely to use this directly, it's mostly used implicitly if you make a `%sing` or `%next` request with a `%v` `care` to a foreign `desk`. Regardless, we'll have a look at it for completeness.
@@ -146,7 +115,7 @@ If the `track` is `%.y` it will just return a `%writ` like:
147If the `track` is `%.n`, the `cage` of the `%writ` will contain a [nako](/docs/arvo/clay/data-types#nako-subscription-response-data) with the relevant data for all changes to a desk between what you have and the `case` requested. It is very large and fairly complicated. The `nako` structure is defined in the `clay.hoon` source file itself rather than in `lull.hoon` or elsewhere since you're unlikely to work with it yourself.
116If the `track` is `%.n`, the `cage` of the `%writ` will contain a [nako](/docs/arvo/clay/data-types#nako-subscription-response-data) with the relevant data for all changes to a desk between what you have and the `case` requested. It is very large and fairly complicated. The `nako` structure is defined in the `clay.hoon` source file itself rather than in `lull.hoon` or elsewhere since you're unlikely to work with it yourself.
149−The `from` and `to` fields of the [moat](/docs/arvo/clay/data-types#moat-clay-range-subscription-request) specify the range of `case`s for which to subscribe. The range is *inclusive*. It can be specified by date or by revision number, whichever you prefer.
118+The `from` and `to` fields of the [moat](/docs/arvo/clay/data-types#moat-clay-range-subscription-request) specify the range of `case`s for which to subscribe. The range is _inclusive_. It can be specified by date or by revision number, whichever you prefer.
151The `path` in the `moat` is a path to a file or directory. If it's `~` it refers to the root of the `desk` in question. This lets you say "only inform me of changes to the `desk` if the specified file or directory exists". If it doesn't exist, Clay will not send you anything.
120The `path` in the `moat` is a path to a file or directory. If it's `~` it refers to the root of the `desk` in question. This lets you say "only inform me of changes to the `desk` if the specified file or directory exists". If it doesn't exist, Clay will not send you anything.
@@ -156,30 +125,28 @@ When you reach the end of the subscribed range of `case`s, Clay will send you a
156[%writ p=~]
125[%writ p=~]
159−### Example
128+#### Example
161[See here for an example of using %many.](/docs/arvo/clay/examples#many)
130[See here for an example of using %many.](/docs/arvo/clay/examples#many)
163−## Cancel Subscription
132+### Cancel Subscription
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.
134To 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.
167−### Example
136+#### Example
169[See here for an example of cancelling a subscription.](/docs/arvo/clay/examples#cancel-subscription)
138[See here for an example of cancelling a subscription.](/docs/arvo/clay/examples#cancel-subscription)
171−# Write and Modify
140+## Write and Modify
175−To write or modify a file, we send Clay a `%info` `task`.
177−### Accepts
142+### `%info` - Write
180−[des=desk dit=nori]
145+[%info des=desk dit=nori]
148+To write or modify a file, we send Clay a `%info` `task`.
183The `%|` tag in the [nori](/docs/arvo/clay/data-types#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#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#miso-clay-ankh-delta) is one of these types of requests:
150The `%|` tag in the [nori](/docs/arvo/clay/data-types#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#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#miso-clay-ankh-delta) is one of these types of requests:
185- `%del` - Delete a file.
152- `%del` - Delete a file.
@@ -187,11 +154,11 @@ The `%|` tag in the [nori](/docs/arvo/clay/data-types#nori-clay-repository-actio
187- `%dif` - This has not yet been implemented so will crash with a `%dif-not-implemented` error.
154- `%dif` - This has not yet been implemented so will crash with a `%dif-not-implemented` error.
188- `%mut` - Change a file. At the time of writing this behaves identically to `%ins` so its use merely informs the reader.
155- `%mut` - Change a file. At the time of writing this behaves identically to `%ins` so its use merely informs the reader.
190−### Returns
157+#### Returns
192Clay does not give any response to an `%info` `task` so don't expect a `sign` back.
159Clay does not give any response to an `%info` `task` so don't expect a `sign` back.
194−### Example
161+#### Example
196Here are examples of using each of these as well as making multiple changes in one request:
163Here are examples of using each of these as well as making multiple changes in one request:
@@ -200,31 +167,26 @@ Here are examples of using each of these as well as making multiple changes in o
200- [%mut](/docs/arvo/clay/examples#mut)
167- [%mut](/docs/arvo/clay/examples#mut)
201- [Multiple Changes](/docs/arvo/clay/examples#multiple-changes)
168- [Multiple Changes](/docs/arvo/clay/examples#multiple-changes)
204−# Manage Mounts
170+## Manage Mounts
206Here we'll look at managing Clay unix mounts programmatically.
172Here we'll look at managing Clay unix mounts programmatically.
208There are four Clay `task`s relevant to mounts:
174There are four Clay `task`s relevant to mounts:
210−- [%boat](#boat) - List mounts.
176+- [%boat](#boat---list-mounts) - List mounts.
211−- [%mont](#mont) - Mount something.
177+- [%mont](#mont---mount) - Mount something.
212−- [%ogre](#ogre) - Unmount something.
178+- [%ogre](#ogre---unmount) - Unmount something.
213−- [%dirk](#dirk) - Commit changes.
179+- [%dirk](#dirk---commit) - Commit changes.
217−A `%boat` `task` requests the list of existing mounts.
181+### `%boat` - List mounts
225−A `%boat` `task` does not take any arguments.
187+A `%boat` `task` requests the list of existing mounts and does not take any arguments.
227−### Returns
189+#### Returns
229The type it returns is a `%hill` `gift`, which looks like:
191The type it returns is a `%hill` `gift`, which looks like:
@@ -234,21 +196,18 @@ The type it returns is a `%hill` `gift`, which looks like:
235...where the `@tas` is the name of the mount point.
197...where the `@tas` is the name of the mount point.
237−### Example
199+#### Example
239[See here for an example of using %boat.](/docs/arvo/clay/examples#boat)
201[See here for an example of using %boat.](/docs/arvo/clay/examples#boat)
241−## `%mont`
203+### `%mont` - Mount
244−A `%mont` `task` mounts the specified `beam` to the specified `term` mount point.
249−[pot=term bem=beam]
206+[%mont pot=term bem=beam]
209+A `%mont` `task` mounts the specified `beam` to the specified `term` mount point.
252A `beam:clay` is the following structure:
211A `beam:clay` is the following structure:
@@ -257,73 +216,69 @@ A `beam:clay` is the following structure:
258You 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).
217You 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).
260−### Returns
219+#### Returns
262Clay does not return a `gift` in response to a `%mont` `%task`.
221Clay does not return a `gift` in response to a `%mont` `%task`.
264−### Example
223+#### Example
266[See here for an example of using %mont.](/docs/arvo/clay/examples#mont)
225[See here for an example of using %mont.](/docs/arvo/clay/examples#mont)
268−## `%ogre`
227+### `%ogre` - Unmount
270−A `%ogre` `task` unmounts the specified mount.
275−[pot=$@(desk beam)]
230+[%ogre pot=$@(desk beam)]
233+A `%ogre` `task` unmounts the specified mount.
278It'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.
235It'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.
280−### Returns
237+#### Returns
282Clay does not return a `gift` in response to a `%ogre` `task`.
239Clay does not return a `gift` in response to a `%ogre` `task`.
284−### Example
241+#### Example
286[See here for an example of using %ogre.](/docs/arvo/clay/examples#ogre)
243[See here for an example of using %ogre.](/docs/arvo/clay/examples#ogre)
288−## `%dirk`
245+### `%dirk` - Commit
290−A `%dirk` `task` commits changes in the target mount.
295−des=desk
248+[%dirk des=desk]
251+A `%dirk` `task` commits changes in the target mount.
298−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.
253+It's defined in `lull.hoon` as taking a `desk` but like [%ogre](#ogre---unmount), it actually takes the name of a mount point rather than a `desk` as is specified.
300−### Returns
255+#### Returns
302Clay does not return a `gift` in response to a `%dirk` `task`.
257Clay does not return a `gift` in response to a `%dirk` `task`.
304−### Example
259+#### Example
306[See here for an example of using %dirk.](/docs/arvo/clay/examples#dirk)
261[See here for an example of using %dirk.](/docs/arvo/clay/examples#dirk)
308−# Merge Desks
263+## Merge Desks
310−## `%merg`
265+### `%merg` - Merge
312−A `%merg` `task` will merge the specified source `desk` into the target local `desk`.
317−$: des=desk :: target
269+ des=desk :: target
318 her=@p dem=desk cas=case :: source
270 her=@p dem=desk cas=case :: source
319 how=germ :: method
271 how=germ :: method
275+A `%merg` `task` will merge the specified source `desk` into the target local `desk`.
322The `germ` specifies the merge strategy. You can refer to the [Strategies](/docs/arvo/clay/using#strategies) section of the [Using Clay](/docs/arvo/clay/using) document for details of each `germ`.
277The `germ` specifies the merge strategy. You can refer to the [Strategies](/docs/arvo/clay/using#strategies) section of the [Using Clay](/docs/arvo/clay/using) document for details of each `germ`.
324If 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.
279If 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.
326−### Returns
281+#### Returns
328Clay will respond to the request with a `%mere` `gift` which looks like:
283Clay will respond to the request with a `%mere` `gift` which looks like:
@@ -344,15 +299,15 @@ If the merge failed, `p` will have a head of `%.n` and then a `[term tang]` wher
347−### Example
302+#### Example
349[See here for an example of using %merg.](/docs/arvo/clay/examples#merg)
304[See here for an example of using %merg.](/docs/arvo/clay/examples#merg)
351−# Permissions
306+## Permissions
353For each file or directory, there is both a read permission and a write permission. Each may be set separately and is either a whitelist or a blacklist (but not both). The whitelist/blacklist contains a `set` of ships and/or groups which are allowed or banned respectively. If it's an empty whitelist it means all foreign ships are denied. If it's an empty blacklist it means all foreign ships are allowed.
308For each file or directory, there is both a read permission and a write permission. Each may be set separately and is either a whitelist or a blacklist (but not both). The whitelist/blacklist contains a `set` of ships and/or groups which are allowed or banned respectively. If it's an empty whitelist it means all foreign ships are denied. If it's an empty blacklist it means all foreign ships are allowed.
355−If permissions are not set for a particular file, they will be inherited from the directory in which it resides. If *that* directory has no permissions set, they will be inherited from another level up, and so on to the `desk`'s root directory. If the root directory has no permissions set, it will have the default permissions of an empty whitelist, meaning "deny all".
310+If permissions are not set for a particular file, they will be inherited from the directory in which it resides. If _that_ directory has no permissions set, they will be inherited from another level up, and so on to the `desk`'s root directory. If the root directory has no permissions set, it will have the default permissions of an empty whitelist, meaning "deny all".
357A group is called a `crew` and is just a `set` of ships with a `@ta` name.
312A group is called a `crew` and is just a `set` of ships with a `@ta` name.
@@ -390,18 +345,16 @@ A `%perm` `task` is for setting permissions, and the other three are for managin
391We'll look at each of these in turn.
346We'll look at each of these in turn.
393−## `%perm`
348+### `%perm` - Set perms
351+[%perm des=desk pax=path rit=rite]
395A `%perm` `task` sets permissions for the target file or directory.
354A `%perm` `task` sets permissions for the target file or directory.
397Note 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.
356Note 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.
402−[des=desk pax=path rit=rite]
405The `pax` path is the file or directory whose permissions you want to change, and the `rite` is this structure:
358The `pax` path is the file or directory whose permissions you want to change, and the `rite` is this structure:
@@ -409,6 +362,7 @@ The `pax` path is the file or directory whose permissions you want to change, an
409 $% [%r red=(unit rule)] :: for read
362 $% [%r red=(unit rule)] :: for read
410 [%w wit=(unit rule)] :: for write
363 [%w wit=(unit rule)] :: for write
411 [%rw red=(unit rule) wit=(unit rule)] :: for read and write
364 [%rw red=(unit rule) wit=(unit rule)] :: for read and write
414Where a `rule` is this structure:
368Where a `rule` is this structure:
@@ -425,51 +379,47 @@ Where a `rule` is this structure:
426As the comment suggests, the `@ta` is the name of a `crew` (group).
380As the comment suggests, the `@ta` is the name of a `crew` (group).
428−### Returns
382+#### Returns
430Clay does not return a `gift` in response to a `%perm` `task`.
384Clay does not return a `gift` in response to a `%perm` `task`.
432−### Example
386+#### Example
434[See here for an example of using %perm.](/docs/arvo/clay/examples#perm)
388[See here for an example of using %perm.](/docs/arvo/clay/examples#perm)
436−## `%cred`
390+### `%cred` - Add group
438−This simply creates a permission group.
443−[nom=@ta cew=crew]
393+[%cred nom=@ta cew=crew]
396+This simply creates a permission group.
446The `nom` is a name for the group and the `crew` is just a `(set ship)`:
398The `nom` is a name for the group and the `crew` is just a `(set ship)`:
449+$ crew (set ship) :: permissions group
401+$ crew (set ship) :: permissions group
452−### Returns
404+#### Returns
454Clay does not return a `gift` in response to a `%cred` `task`.
406Clay does not return a `gift` in response to a `%cred` `task`.
456−### Example
408+#### Example
458[See here for an example of using %cred.](/docs/arvo/clay/examples#cred)
410[See here for an example of using %cred.](/docs/arvo/clay/examples#cred)
460−## `%crew`
412+### `%crew` - Get groups
462−This retrieves all permission groups.
418+This retrieves all permission groups.
470A `%crew` `task` takes no arguments.
420A `%crew` `task` takes no arguments.
472−### Returns
422+#### Returns
474Clay wil return a `%cruz` `gift`. It looks like:
424Clay wil return a `%cruz` `gift`. It looks like:
@@ -479,23 +429,21 @@ Clay wil return a `%cruz` `gift`. It looks like:
480The `cez` is just a map from group name to `crew` which is just a `(set ship)`.
430The `cez` is just a map from group name to `crew` which is just a `(set ship)`.
482−### Example
432+#### Example
484[See here for an example of using %crew.](/docs/arvo/clay/examples#crew)
434[See here for an example of using %crew.](/docs/arvo/clay/examples#crew)
486−## `%crow`
436+### `%crow` - Group files
488−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.
493−nom=@ta
439+[%crow nom=@ta]
442+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.
496The `nom` is the name of a `crew`.
444The `nom` is the name of a `crew`.
498−### Returns
446+#### Returns
500The `gift` you get back is a `%croz` which looks like:
448The `gift` you get back is a `%croz` which looks like:
@@ -509,19 +457,19 @@ The `gift` you get back is a `%croz` which looks like:
509+$ regs (map path rule) :: rules for paths
457+$ regs (map path rule) :: rules for paths
512−### Example
460+#### Example
514[See here for an example of using %crow.](/docs/arvo/clay/examples#crow)
462[See here for an example of using %crow.](/docs/arvo/clay/examples#crow)
516−# Foreign Ships
464+## Foreign Ships
518Here we'll looking at making Clay requests to a foreign ship.
466Here we'll looking at making Clay requests to a foreign ship.
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.
468As 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.
522−## `%warp` - Remote
470+### `%warp` - Remote
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.
472+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---read-and-track) section.
526Clay only allows a subset of `care`s to be used remotely. They are:
474Clay only allows a subset of `care`s to be used remotely. They are:
@@ -538,11 +486,11 @@ The foreign ship will respond only if correct permissions have been set. See the
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.
487Note 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.
541−### Example
489+#### Example
543[See here for examples of requests to foreign ships.](/docs/arvo/clay/examples#foreign-ships)
491[See here for examples of requests to foreign ships.](/docs/arvo/clay/examples#foreign-ships)
545−## `%merg` - Remote
493+### `%merg` - Remote
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.
495To 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.
@@ -550,6 +498,6 @@ The foreign ship will respond only if correct permissions have been set. See the
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.
499Note 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.
553−### Example
501+#### Example
555[See here for examples of requests to foreign ships.](/docs/arvo/clay/examples#foreign-ships)
503[See here for examples of requests to foreign ships.](/docs/arvo/clay/examples#foreign-ships)