@@ -7,7 +7,7 @@ template = "doc.html"
77# Contents
88
99- [Introduction](#introduction)
10−- [Read and Subscribe](#read-and-subscribe)
10+- [%warp](#warp) - Read and Subscribe.
1111 - [%sing](#sing) - Read a file or directory.
1212 - [%next](#next) - Subscribe for the next change to a file or directory.
1313 - [%mult](#mult) - Subscribe for the next change to a set of files and/or directories.
@@ -28,8 +28,8 @@ template = "doc.html"
2828 - [%crew](#crew) - Get permission groups.
2929 - [%crow](#crow) - Get group usage.
3030- [Foreign Ships](#foreign-ships)
31− - [%warp](#warp) - Read a file on a foreign ship.
32− - [%merg](#merg) - Merge from a foreign `desk`.
31+ - [%warp](#warp-remote) - Read a file on a foreign ship.
32+ - [%merg](#merg-remote) - Merge from a foreign `desk`.
3333
3434# Introduction
3535
@@ -37,14 +37,16 @@ This document details all the `task`s you're likely to use to interact with Clay
3737
3838The 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.
3939
40−# Read and Subscribe
41−
42−Here we'll look at reading files and subscribing to changes. This is done by sending Clay a `%warp` `task`:
40+# `%warp`
4341
4442```hoon
4543[%warp wer=ship rif=riff] :: internal file req
4644```
4745
46+A `%warp` `task` is for reading a subscribing to files and directories.
47+
48+### Accepts
49+
4850The `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:
4951
5052- `%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/
5456
5557We'll look at each of these in more detail below.
5658
59+### Returns
60+
5761Clay responds to a `%mult` request with a `%wris` `gift`, and the rest with a `%writ` `gift`.
5862
5963A `%wris` `gift` looks like:
@@ -72,19 +76,23 @@ The `unit` of the [riot](@/docs/arvo/clay/data-types.md#riot-clay-response) will
7276
7377Now we'll look at each of the `rave` request types in turn.
7478
75−## %sing
79+## `%sing`
7680
7781```hoon
7882[%sing =mood]
7983```
8084
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.
85+This `rave` is for reading a single file or directory immediately.
86+
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.
8288
8389The [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`.
8490
91+### Example
92+
8593[See here for an example of using %sing.](@/docs/arvo/clay/examples.md#sing)
8694
87−## %next
95+## `%next`
8896
8997```hoon
9098[%next =mood] :: await next version
@@ -94,9 +102,11 @@ This subscribes to the next version of the specified file. See [here](@/docs/arv
94102
95103If 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`.
96104
105+### Example
106+
97107[See here for an example of using %next.](@/docs/arvo/clay/examples.md#next)
98108
99−## %mult
109+## `%mult`
100110
101111```hoon
102112[%mult =mool] :: next version of any
@@ -114,9 +124,11 @@ The `mool` specified in the request is this structure:
114124
115125You 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.
116126
127+### Example
128+
117129[See here for an example of using %mult.](@/docs/arvo/clay/examples.md#mult)
118130
119−## %many
131+## `%many`
120132
121133```hoon
122134[%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
144156[%writ p=~]
145157```
146158
159+### Example
160+
147161[See here for an example of using %many.](@/docs/arvo/clay/examples.md#many)
148162
149163## Cancel Subscription
150164
151165To 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.
152166
167+### Example
168+
153169[See here for an example of cancelling a subscription.](@/docs/arvo/clay/examples.md#cancel-subscription)
154170
155171# Write and Modify
156172
157−## %info
158−
159−To write or modify a file, we send Clay a `%info` `task`:
173+## `%info`
160174
161175```hoon
162176[%info des=desk dit=nori] :: internal edit
163177```
164178
179+To write or modify a file, we send Clay a `%info` `task`.
180+
181+### Accepts
182+
165183The `%|` 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:
166184
167185- `%del` - Delete a file.
@@ -169,8 +187,12 @@ The `%|` tag in the [nori](@/docs/arvo/clay/data-types.md#nori-clay-repository-a
169187- `%dif` - This has not yet been implemented so will crash with a `%dif-not-implemented` error.
170188- `%mut` - Change a file. At the time of writing this behaves identically to `%ins` so its use merely informs the reader.
171189
190+### Returns
191+
172192Clay does not give any response to an `%info` `task` so don't expect a `sign` back.
173193
194+### Example
195+
174196Here are examples of using each of these as well as making multiple changes in one request:
175197
176198- [%del](@/docs/arvo/clay/examples.md#del)
@@ -190,15 +212,21 @@ There are four Clay `task`s relevant to mounts:
190212- [%ogre](#ogre) - Unmount something.
191213- [%dirk](#dirk) - Commit changes.
192214
193−## %boat
194−
195−This type of `task` will request the list of existing mounts. It looks like:
215+## `%boat`
196216
197217```hoon
198218[%boat ~]
199219```
200220
201−Pretty simple. The type it returns is a `%hill` `gift`, which looks like:
221+A `%boat` `task` requests the list of existing mounts.
222+
223+### Accepts
224+
225+A `%boat` `task` does not take any arguments.
226+
227+### Returns
228+
229+The type it returns is a `%hill` `gift`, which looks like:
202230
203231```hoon
204232[%hill p=(list @tas)]
@@ -206,16 +234,20 @@ Pretty simple. The type it returns is a `%hill` `gift`, which looks like:
206234
207235...where the `@tas` is the name of the mount point.
208236
209−[See here for an example of using %boat.](@/docs/arvo/clay/examples.md#boat)
237+### Example
210238
211−## %mont
239+[See here for an example of using %boat.](@/docs/arvo/clay/examples.md#boat)
212240
213−This type of `task` mounts the specified `beam` to the specified `term` mount point. It looks like:
241+## `%mont`
214242
215243```hoon
216244[%mont pot=term bem=beam]
217245```
218246
247+A `%mont` `task` mounts the specified `beam` to the specified `term` mount point.
248+
249+### Accepts
250+
219251A `beam:clay` is the following structure:
220252
221253```hoon
@@ -224,37 +256,57 @@ A `beam:clay` is the following structure:
224256
225257You 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).
226258
227−[See here for an example of using %mont.](@/docs/arvo/clay/examples.md#mont)
259+### Returns
260+
261+Clay does not return a `gift` in response to a `%mont` `%task`.
228262
229−## %ogre
263+### Example
264+
265+[See here for an example of using %mont.](@/docs/arvo/clay/examples.md#mont)
230266
231−This type of `task` unmounts the specified mount. It's defined in `lull.hoon` as:
267+## `%ogre`
232268
233269```hoon
234270[%ogre pot=$@(desk beam)]
235271```
236272
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.
238274
239−[See here for an example of using %ogre.](@/docs/arvo/clay/examples.md#ogre)
275+### Accepts
276+
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.
278+
279+### Returns
240280
241−## %dirk
281+Clay does not return a `gift` in response to a `%ogre` `task`.
242282
243−This type of `task` commits changes in the target mount. It's defined in `lull.hoon` as:
283+### Example
284+
285+[See here for an example of using %ogre.](@/docs/arvo/clay/examples.md#ogre)
286+
287+## `%dirk`
244288
245289```hoon
246290[%dirk des=desk]
247291```
248292
249−... but like [%ogre](#ogre), it actually takes the name of a mount point rather than a `desk` as is specified.
293+### Accepts
294+
295+A `%dirk` `task` commits changes in the target mount.
296+
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.
298+
299+### Returns
300+
301+Clay does not return a `gift` in response to a `%dirk` `task`.
302+
303+### Example
250304
251305[See here for an example of using %dirk.](@/docs/arvo/clay/examples.md#dirk)
252306
253307# Merge Desks
254308
255−## %merg
256−
257−A `%merg` `task` will merge the specified source `desk` into the target local `desk`. It looks like:
309+## `%merg`
258310
259311```hoon
260312$: %merg :: merge desks
@@ -264,10 +316,16 @@ $: %merg :: merge desks
264316== ::
265317```
266318
319+A `%merg` `task` will merge the specified source `desk` into the target local `desk`.
320+
321+### Accepts
322+
267323The `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`.
268324
269325If 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.
270326
327+### Returns
328+
271329Clay will respond to the request with a `%mere` `gift` which looks like:
272330
273331```hoon
@@ -287,6 +345,8 @@ If the merge failed, `p` will have a head of `%.n` and then a `[term tang]` wher
287345]
288346```
289347
348+### Example
349+
290350[See here for an example of using %merg.](@/docs/arvo/clay/examples.md#merg)
291351
292352# Permissions
@@ -331,18 +391,18 @@ A `%perm` `task` is for setting permissions, and the other three are for managin
331391
332392We'll look at each of these in turn.
333393
334−## %perm
335−
336−This sets permissions for the target file or directory.
337−
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.
339−
340−A `%perm` `task` looks like:
394+## `%perm`
341395
342396```hoon
343397[%perm des=desk pax=path rit=rite] :: change permissions
344398```
345399
400+A `%perm` `task` sets permissions for the target file or directory.
401+
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.
403+
404+### Accepts
405+
346406The `pax` path is the file or directory whose permissions you want to change, and the `rite` is this structure:
347407
348408```hoon
@@ -366,33 +426,52 @@ Where a `rule` is this structure:
366426
367427As the comment suggests, the `@ta` is the name of a `crew` (group).
368428
369−[See here for an example of using %perm.](@/docs/arvo/clay/examples.md#perm)
429+### Returns
430+
431+Clay does not return a `gift` in response to a `%perm` `task`.
370432
371−## %cred
433+### Example
434+
435+[See here for an example of using %perm.](@/docs/arvo/clay/examples.md#perm)
372436
373−This simply creates a permission group. The task looks like this:
437+## `%cred`
374438
375439```hoon
376440[%cred nom=@ta cew=crew] :: set permission group
377441```
378442
443+This simply creates a permission group.
444+
445+### Accepts
446+
379447The `nom` is a name for the group and the `crew` is just a `(set ship)`:
380448
381449```hoon
382450+$ crew (set ship) :: permissions group
383451```
384452
385−[See here for an example of using %cred.](@/docs/arvo/clay/examples.md#cred)
453+### Returns
386454
387−## %crew
455+Clay does not return a `gift` in response to a `%cred` `task`.
388456
389−This retrieves all permission groups. It looks like:
457+### Example
458+
459+[See here for an example of using %cred.](@/docs/arvo/clay/examples.md#cred)
460+
461+## `%crew`
390462
391463```hoon
392464[%crew ~] :: permission groups
393465```
466+This retrieves all permission groups.
467+
468+### Accepts
469+
470+A `%crew` `task` takes no arguments.
471+
472+### Returns
394473
395−Clay wil return a sign containing a `%cruz` `gift`. It looks like:
474+Clay wil return a `%cruz` `gift`. It looks like:
396475
397476```hoon
398477[%cruz cez=(map @ta crew)] :: permission groups
@@ -400,16 +479,24 @@ Clay wil return a sign containing a `%cruz` `gift`. It looks like:
400479
401480The `cez` is just a map from group name to `crew` which is just a `(set ship)`.
402481
403−[See here for an example of using %crew.](@/docs/arvo/clay/examples.md#crew)
482+### Example
404483
405−## %crow
484+[See here for an example of using %crew.](@/docs/arvo/clay/examples.md#crew)
406485
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`
408487
409488```hoon
410489[%crow nom=@ta] :: group usage
411490```
412491
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.
493+
494+### Accepts
495+
496+The `nom` is the name of a `crew`.
497+
498+### Returns
499+
413500The `gift` you get back is a `%croz` which looks like:
414501
415502```hoon
@@ -422,6 +509,8 @@ The `gift` you get back is a `%croz` which looks like:
422509+$ regs (map path rule) :: rules for paths
423510```
424511
512+### Example
513+
425514[See here for an example of using %crow.](@/docs/arvo/clay/examples.md#crow)
426515
427516# Foreign Ships
@@ -430,9 +519,9 @@ Here we'll looking at making Clay requests to a foreign ship.
430519
431520As 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.
432521
433−## %warp
522+## `%warp` - Remote
434523
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.
436525
437526Clay only allows a subset of `care`s to be used remotely. They are:
438527
@@ -449,9 +538,11 @@ The foreign ship will respond only if correct permissions have been set. See the
449538
450539Note 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.
451540
541+### Example
542+
452543[See here for examples of requests to foreign ships.](@/docs/arvo/clay/examples.md#foreign-ships)
453544
454−## %merg
545+## `%merg` - Remote
455546
456547To 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.
457548
@@ -459,4 +550,6 @@ The foreign ship will respond only if correct permissions have been set. See the
459550
460551Note 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.
461552
553+### Example
554+
462555[See here for examples of requests to foreign ships.](@/docs/arvo/clay/examples.md#foreign-ships)