git.iko.soy/urbit.org
on master help sign in
clay: stylistic fixes
fee2eb2tinnus-napbus
arvo/clay/foreign-requests.md+10−10
compare with master
unifiedsplit
@@ -4,9 +4,9 @@ weight = 11
4template = "doc.html"
4template = "doc.html"
5+++
5+++
6
6
7−Here we'll looking at making `clay` requests to a foreign ship.
7+Here we'll looking at making Clay requests to a foreign ship.
8
8
9−As 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`).
9+As 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`).
10
10
11## Contents
11## Contents
12
12
@@ -15,9 +15,9 @@ As it currently stands, it's not possible to write to a foreign desk. Additional
15
15
16## %warp
16## %warp
17
17
18−To read files on a foreign desk, you just send clay a `%warp` `task:clay` (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](@/docs/arvo/clay/read.md) document.
18+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](@/docs/arvo/clay/read.md) document.
19
19
20−Clay only allows a subset of cares to be used remotely. They are:
20+Clay only allows a subset of `care`s to be used remotely. They are:
21
21
22- `%u` - Check for existence of file.
22- `%u` - Check for existence of file.
23- `%v` - Get entire `dome:clay` state of a desk.
23- `%v` - Get entire `dome:clay` state of a desk.
@@ -30,13 +30,13 @@ Any other `care` will crash with a `%clay-bad-foreign-request-care` error.
30
30
31The foreign ship will respond only if correct permissions have been set. See the [Permissions](@/docs/arvo/clay/permissions.md) document for details.
31The foreign ship will respond only if correct permissions have been set. See the [Permissions](@/docs/arvo/clay/permissions.md) document for details.
32
32
33−Note 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.
33+Note 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.
34
34
35Example:
35Example:
36
36
37We'll use a fake ~nes as the the foreign ship and a fake ~zod as the local ship.
37We'll use a fake ~nes as the the foreign ship and a fake ~zod as the local ship.
38
38
39−First we'll set permissions on the foreign ship. Here's a simple thread that just sends a task to clay:
39+First we'll set permissions on the foreign ship. Here's a simple thread that just sends a `task` to Clay:
40
40
41`send-clay-task.hoon`
41`send-clay-task.hoon`
42
42
@@ -63,7 +63,7 @@ Create a file called `foo.txt` in the `%home` of ~nes. Save the above thread to
63> -send-clay-task [%perm %home /foo/txt %rw `[%white (sy [%.y ~zod]~)] `[%white (sy [%.y ~zod]~)]]
63> -send-clay-task [%perm %home /foo/txt %rw `[%white (sy [%.y ~zod]~)] `[%white (sy [%.y ~zod]~)]]
64```
64```
65
65
66−If we scry the file for its permissions with a `%p` care, we'll see ~zod is now whitelisted:
66+If we scry the file for its permissions with a `%p` `care`, we'll see ~zod is now whitelisted:
67
67
68```hoon
68```hoon
69> .^([r=dict:clay w=dict:clay] %cp /===/foo/txt)
69> .^([r=dict:clay w=dict:clay] %cp /===/foo/txt)
@@ -139,8 +139,8 @@ call: failed
139
139
140## %merg
140## %merg
141
141
142−To merge a foreign desk into a local one, you just send clay a `%merg` `task:clay` (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](@/docs/arvo/clay/merge.md) document.
142+To 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](@/docs/arvo/clay/merge.md) document.
143
143
144−The foreign ship will respond only if correct permissions have been set. See the [Permissions](@/docs/arvo/clay/permissions.md) document for details. By default, a ship's `%kids` desk is set to be publicly readable, so unless permissions have been manually modified, you should be able to merge from any `%kids` desk.
144+The foreign ship will respond only if correct permissions have been set. See the [Permissions](@/docs/arvo/clay/permissions.md) document for details. By default, a ship's `%kids` desk is set to be publicly readable, so unless permissions have been manually modified, you should be able to merge from any `%kids` `desk`.
145
145
146−Note 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.
146+Note 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.
arvo/clay/merge.md+11−11
@@ -4,9 +4,9 @@ weight = 9
4template = "doc.html"
4template = "doc.html"
5+++
5+++
6
6
7−Here we'll look at merging desks programmatically.
7+Here we'll look at merging `desk`s programmatically.
8
8
9−A `%merg` tagged `task:clay` will merge the specified source desk into the target local desk. It looks like:
9+A `%merg` `task` will merge the specified source `desk` into the target local `desk`. It looks like:
10
10
11```hoon
11```hoon
12$: %merg :: merge desks
12$: %merg :: merge desks
@@ -36,9 +36,9 @@ The `germ` specifies the merge strategy and looks like:
36
36
37You 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`.
37You 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`.
38
38
39−If 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.
39+If 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.
40
40
41−Clay will respond to the request with a `%mere` tagged `gift:clay` which looks like:
41+Clay will respond to the request with a `%mere` `gift` which looks like:
42
42
43```hoon
43```hoon
44[%mere p=(each (set path) (pair term tang))] :: merge result
44[%mere p=(each (set path) (pair term tang))] :: merge result
@@ -59,7 +59,7 @@ If the merge failed, `p` will have a head of `%.n` and then a `[term tang]` wher
59
59
60Example:
60Example:
61
61
62−Here's a thread that sends the given `task:clay` to clay and prints the `gift:clay` response:
62+Here's a thread that sends the given `task` to Clay and prints the `gift` response:
63
63
64`send-task.hoon`
64`send-task.hoon`
65
65
@@ -82,21 +82,21 @@ Here's a thread that sends the given `task:clay` to clay and prints the `gift:cl
82
82
83Save it to `ted/send-task.hoon` and `|commit %home`.
83Save it to `ted/send-task.hoon` and `|commit %home`.
84
84
85−First, let's try creating a new desk:
85+First, let's try creating a new `desk`:
86
86
87```hoon
87```hoon
88> -send-task-take-gift [%merg %foo our %home da+now %init]
88> -send-task-take-gift [%merg %foo our %home da+now %init]
89[%mere p=[%.y p={}]]
89[%mere p=[%.y p={}]]
90```
90```
91
91
92−Now if we scry for our desks we'll see `%foo` is there:
92+Now if we scry for our `desk`s we'll see `%foo` is there:
93
93
94```hoon
94```hoon
95> .^((set desk) %cd /===)
95> .^((set desk) %cd /===)
96{%home %foo %kids}
96{%home %foo %kids}
97```
97```
98
98
99−Next, we'll create a merge conflict and try a couple of things. Mount `%foo` with `|mount /=foo=`, then add a `foo.txt` to both desks but with different text in each and `|commit` them.
99+Next, we'll create a merge conflict and try a couple of things. Mount `%foo` with `|mount /=foo=`, then add a `foo.txt` to both `desk`s but with different text in each and `|commit` them.
100
100
101Now we'll try merging `%home` into `%foo` with a `%mate` strategy:
101Now we'll try merging `%home` into `%foo` with a `%mate` strategy:
102
102
@@ -132,15 +132,15 @@ Now the merge has succeeded and the `%mere` notes the file with a merge conflict
132: /~zod/foo/6/foo/txt
132: /~zod/foo/6/foo/txt
133```
133```
134
134
135−...you can see it's overwritten the `foo/txt` in the `%foo` desk and the `%mere` now has an empty set, indicating no merge conflicts.
135+...you can see it's overwritten the `foo/txt` in the `%foo` `desk` and the `%mere` now has an empty `set`, indicating no merge conflicts.
136
136
137−Next, let's look at subscribing for future changes. Since the `case` is specified explicitly in the `%merge` task, we can set in in the future:
137+Next, let's look at subscribing for future changes. Since the `case` is specified explicitly in the `%merge` `task`, we can set it in the future:
138
138
139```hoon
139```hoon
140> -send-task-take-gift [%merg %foo our %home da+(add ~m2 now) %only-that]
140> -send-task-take-gift [%merg %foo our %home da+(add ~m2 now) %only-that]
141```
141```
142
142
143−Now change the text in the `foo.txt` in the `%home` desk, hit backspace to detach the thread and `|commit %home`. After the two minutes pass you should see:
143+Now change the text in the `foo.txt` in the `%home` `desk`, hit backspace to detach the thread and `|commit %home`. After the two minutes pass you should see:
144
144
145```hoon
145```hoon
146[/foo [%clay [%mere p=[%.y p={}]]]]
146[/foo [%clay [%mere p=[%.y p={}]]]]
arvo/clay/mounts.md+14−14
@@ -4,11 +4,11 @@ weight = 8
4template = "doc.html"
4template = "doc.html"
5+++
5+++
6
6
7−Here we'll look at managing clay unix mounts programmatically.
7+Here we'll look at managing Clay unix mounts programmatically.
8
8
9## Contents
9## Contents
10
10
11−There are four `task:clay` tags relevant to mounts:
11+There are four Clay `task`s relevant to mounts:
12
12
13- [%boat](#boat) - List mounts.
13- [%boat](#boat) - List mounts.
14- [%mont](#mont) - Mount something.
14- [%mont](#mont) - Mount something.
@@ -17,13 +17,13 @@ There are four `task:clay` tags relevant to mounts:
17
17
18## %boat
18## %boat
19
19
20−This type of `task:clay` will request the list of existing mounts. It looks like:
20+This type of `task` will request the list of existing mounts. It looks like:
21
21
22```hoon
22```hoon
23[%boat ~]
23[%boat ~]
24```
24```
25
25
26−Pretty simple. The type it returns is a `%hill` tagged `gift:clay`, which looks like:
26+Pretty simple. The type it returns is a `%hill` `gift`, which looks like:
27
27
28```hoon
28```hoon
29[%hill p=(list @tas)]
29[%hill p=(list @tas)]
@@ -33,7 +33,7 @@ Pretty simple. The type it returns is a `%hill` tagged `gift:clay`, which looks
33
33
34Example:
34Example:
35
35
36−Here's a thread that sends a `task:clay` and takes a `gift:clay` in response:
36+Here's a thread that sends a `task` and takes a `gift` in response:
37
37
38`send-task-take-gift.hoon`
38`send-task-take-gift.hoon`
39
39
@@ -65,7 +65,7 @@ Save it to `ted/send-task-take-gift.hoon`, `|commit %home`, and run it like:
65
65
66## %mont
66## %mont
67
67
68−This type of `task:clay` mounts the specified `beam:clay` to the specified `term` mount point. It looks like:
68+This type of `task` mounts the specified `beam:clay` to the specified `term` mount point. It looks like:
69
69
70```hoon
70```hoon
71[%mont pot=term bem=beam]
71[%mont pot=term bem=beam]
@@ -81,7 +81,7 @@ You can mount the whole desk with a `path` of `/`, and you can also mount subdir
81
81
82Example:
82Example:
83
83
84−Here's a thread which will send the given `task:clay` to clay.
84+Here's a thread which will send the given `task` to Clay.
85
85
86`send-task.hoon`
86`send-task.hoon`
87
87
@@ -108,7 +108,7 @@ Save it to `ted/send-task.hoon`, `|commit %home` and run it like:
108> -send-task [%mont %kids [our %kids da+now] /]
108> -send-task [%mont %kids [our %kids da+now] /]
109```
109```
110
110
111−If you look in your pier, you should now see a `kids` folder which contains the contents of that desk.
111+If you look in your pier, you should now see a `kids` folder which contains the contents of that `desk`.
112
112
113If we make a `%boat` request as detailed in the [%boat](#boat) section, we'll now see the mount point listed:
113If we make a `%boat` request as detailed in the [%boat](#boat) section, we'll now see the mount point listed:
114
114
@@ -117,13 +117,13 @@ If we make a `%boat` request as detailed in the [%boat](#boat) section, we'll no
117[%hill p=~[%kids %home]]
117[%hill p=~[%kids %home]]
118```
118```
119
119
120−Note the mount point doesn't need to match a desk, file or directory. We can also do:
120+Note the mount point doesn't need to match a `desk`, file or directory. We can also do:
121
121
122```hoon
122```hoon
123> -send-task [%mont %wibbly-wobbly [our %home da+now] /]
123> -send-task [%mont %wibbly-wobbly [our %home da+now] /]
124```
124```
125
125
126−And you'll now see that there's a `wibbly-wobbly` folder with the contents of the `%home` desk. You'll also notice we can mount the same file or directory more than once. There's no problem having `%home` mounted to both `home` and `wibbly-wobbly`. The only requirement is that their mount points be unique.
126+And you'll now see that there's a `wibbly-wobbly` folder with the contents of the `%home` `desk`. You'll also notice we can mount the same file or directory more than once. There's no problem having `%home` mounted to both `home` and `wibbly-wobbly`. The only requirement is that their mount points be unique.
127
127
128Let's try mounting a subdirectory and a single folder:
128Let's try mounting a subdirectory and a single folder:
129
129
@@ -136,13 +136,13 @@ If you look in your pier you'll now see a `gen` folder with the contents of `/ge
136
136
137## %ogre
137## %ogre
138
138
139−This type of `task:clay` unmounts the specified mount. It's defined in `lull.hoon` as:
139+This type of `task` unmounts the specified mount. It's defined in `lull.hoon` as:
140
140
141```hoon
141```hoon
142[%ogre pot=$@(desk beam)]
142[%ogre pot=$@(desk beam)]
143```
143```
144
144
145−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.
145+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.
146
146
147Using the thread from the [%mont](#mont) section, we can unmount `%kids` like:
147Using the thread from the [%mont](#mont) section, we can unmount `%kids` like:
148
148
@@ -183,7 +183,7 @@ This type of `task:clay` commits changes in the target mount. It's defined in `l
183
183
184Example:
184Example:
185
185
186−With your `%home` desk mounted, try adding a file and, using the thread from the [%mont](#mont) section, send a `%dirk` to commit the change:
186+With your `%home` `desk` mounted, try adding a file and, using the thread from the [%mont](#mont) section, send a `%dirk` to commit the change:
187
187
188```hoon
188```hoon
189> -send-task [%dirk %home]
189> -send-task [%dirk %home]
@@ -192,4 +192,4 @@ With your `%home` desk mounted, try adding a file and, using the thread from the
192
192
193Clay will print the changed files to the dojo with a leading `+`, `-` or `:` to indicate a new file, deleted file and changed file respectively.
193Clay will print the changed files to the dojo with a leading `+`, `-` or `:` to indicate a new file, deleted file and changed file respectively.
194
194
195−If you have the same desk mounted to multiple points, a committed change in one mount will also update the others.
195+If you have the same `desk` mounted to multiple points, a committed change in one mount will also update the others.
arvo/clay/permissions.md+16−16
@@ -17,7 +17,7 @@ Here we'll look at file permissions.
17
17
18For 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.
18For 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.
19
19
20−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".
20+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".
21
21
22A group is called a `crew` and is just a `set` of ships with a `@ta` name.
22A group is called a `crew` and is just a `set` of ships with a `@ta` name.
23
23
@@ -38,20 +38,20 @@ The `src` path is where the permissions were inherited from and the `real` is th
38 == ::
38 == ::
39```
39```
40
40
41−So if we scry for permissions with a `%p` care, it'll look like:
41+So if we scry for permissions with a `%p` `care`, it'll look like:
42
42
43```hoon
43```hoon
44> .^([r=dict:clay w=dict:clay] %cp /===/lib/strandio/hoon)
44> .^([r=dict:clay w=dict:clay] %cp /===/lib/strandio/hoon)
45[r=[src=/ rul=[mod=%white who=[p={} q={}]]] w=[src=/ rul=[mod=%white who=[p={} q={}]]]]
45[r=[src=/ rul=[mod=%white who=[p={} q={}]]] w=[src=/ rul=[mod=%white who=[p={} q={}]]]]
46```
46```
47
47
48−There are four permission-related tasks which you can pass to clay.
48+There are four permission-related `task`s which you can pass to Clay.
49
49
50−A `%perm` task is for setting permissions, and the other three are for managing groups:
50+A `%perm` `task` is for setting permissions, and the other three are for managing groups:
51
51
52−- `%cred` - add permission group
52+- `%cred` - Add permission group.
53−- `%crew` - get permission groups
53+- `%crew` - Get permission groups.
54−- `%crow` - get group usage
54+- `%crow` - Get group usage.
55
55
56We'll look at each of these in turn.
56We'll look at each of these in turn.
57
57
@@ -61,7 +61,7 @@ This sets permissions for the target file or directory.
61
61
62Note 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.
62Note 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.
63
63
64−A `%perm` tagged `task:clay` looks like:
64+A `%perm` `task` looks like:
65
65
66```hoon
66```hoon
67[%perm des=desk pax=path rit=rite] :: change permissions
67[%perm des=desk pax=path rit=rite] :: change permissions
@@ -92,7 +92,7 @@ As the comment suggests, the `@ta` is the name of a `crew` (group).
92
92
93Example:
93Example:
94
94
95−Here's a generic thread that just sends the given `task:clay` to clay so we can try a few different things:
95+Here's a generic thread that just sends the given `task` to Clay so we can try a few different things:
96
96
97`send-clay-task.hoon`
97`send-clay-task.hoon`
98
98
@@ -121,7 +121,7 @@ Save it to `ted/send-clay-task.hoon` and `|commit %home`. Now, let's allow `~nes
121
121
122...and we'll do a `%p` scry to see that the permission was set:
122...and we'll do a `%p` scry to see that the permission was set:
123
123
124−```hood
124+```hoon
125> .^([r=dict:clay w=dict:clay] %cp /===/gen/hood/hi/hoon)
125> .^([r=dict:clay w=dict:clay] %cp /===/gen/hood/hi/hoon)
126[r=[src=/gen/hood/hi/hoon rul=[mod=%white who=[p={~nes} q={}]]] w=[src=/ rul=[mod=%white who=[p={} q={}]]]]
126[r=[src=/gen/hood/hi/hoon rul=[mod=%white who=[p={~nes} q={}]]] w=[src=/ rul=[mod=%white who=[p={} q={}]]]]
127```
127```
@@ -178,7 +178,7 @@ For example, to remove a read permission (or write if you specify `%w`):
178> -send-clay-task [%perm %home /gen/help/hoon %rw ~ ~]
178> -send-clay-task [%perm %home /gen/help/hoon %rw ~ ~]
179```
179```
180
180
181−```hood
181+```hoon
182> .^([r=dict:clay w=dict:clay] %cp /===/gen/help/hoon)
182> .^([r=dict:clay w=dict:clay] %cp /===/gen/help/hoon)
183[r=[src=/ rul=[mod=%white who=[p={} q={}]]] w=[src=/ rul=[mod=%white who=[p={} q={}]]]]
183[r=[src=/ rul=[mod=%white who=[p={} q={}]]] w=[src=/ rul=[mod=%white who=[p={} q={}]]]]
184```
184```
@@ -211,7 +211,7 @@ We'll use the same thread from the [%perm](#perm) example. Try:
211-send-clay-task [%crew 'foo' (sy ~[~zod ~nec ~bud ~wes ~sev])]
211-send-clay-task [%crew 'foo' (sy ~[~zod ~nec ~bud ~wes ~sev])]
212```
212```
213
213
214−We'll check it with the next kind of task: [%crew](#crew).
214+We'll check it with the next kind of `task`: [%crew](#crew).
215
215
216## %crew
216## %crew
217
217
@@ -221,7 +221,7 @@ This retrieves all permission groups. It looks like:
221[%crew ~] :: permission groups
221[%crew ~] :: permission groups
222```
222```
223
223
224−Clay wil return a sign containing a `gift:clay` with a `%cruz` tag. It looks like:
224+Clay wil return a sign containing a `%cruz` `gift`. It looks like:
225
225
226```hoon
226```hoon
227[%cruz cez=(map @ta crew)] :: permission groups
227[%cruz cez=(map @ta crew)] :: permission groups
@@ -231,7 +231,7 @@ The `cez` is just a map from group name to `crew` which is just a `(set ship)`.
231
231
232Example:
232Example:
233
233
234−Here's a generic thread that sends the given `task:clay` and receives a gift which it just prints to the dojo.
234+Here's a generic thread that sends the given `task` and receives a `gift` which it just prints to the dojo.
235
235
236`send-task-take-gift.hoon`
236`send-task-take-gift.hoon`
237
237
@@ -263,13 +263,13 @@ Save the above to `ted/send-task-take-gift.hoon` and `|commit %home`. Now we'll
263
263
264## %crow
264## %crow
265
265
266−This is the last group task. It retrieves all files and directories in all desks which have permissions set for the group in question. It will not return inherited permissions, only those explicitly set. It looks like:
266+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:
267
267
268```hoon
268```hoon
269[%crow nom=@ta] :: group usage
269[%crow nom=@ta] :: group usage
270```
270```
271
271
272−The `gift:clay` you get back is a `%croz` which looks like:
272+The `gift` you get back is a `%croz` which looks like:
273
273
274```hoon
274```hoon
275[%croz rus=(map desk [r=regs w=regs])] :: rules for group
275[%croz rus=(map desk [r=regs w=regs])] :: rules for group
arvo/clay/read.md+30−30
@@ -4,7 +4,7 @@ weight = 6
4template = "doc.html"
4template = "doc.html"
5+++
5+++
6
6
7−Here we'll look at reading files and subscribing to changes. We'll do this by sending clay a `card:agent:gall` containing a `%warp` tagged `task:clay`.
7+Here we'll look at reading files and subscribing to changes. We'll do this by sending Clay a `card` containing a `%warp` `task`.
8
8
9## Contents
9## Contents
10
10
@@ -12,12 +12,12 @@ Here we'll look at reading files and subscribing to changes. We'll do this by se
12- [%sing](#sing) - Read a single file or directory.
12- [%sing](#sing) - Read a single file or directory.
13- [%next](#next) - Subscribe for the next change to a file or directory.
13- [%next](#next) - Subscribe for the next change to a file or directory.
14- [%mult](#mult) - Subscribe for the next change to a set of files and/or directories.
14- [%mult](#mult) - Subscribe for the next change to a set of files and/or directories.
15−- [%many](#many) - Track changes to a desk for the specified range of revisions.
15+- [%many](#many) - Track changes to a `desk` for the specified range of revisions.
16- [Cancel Subsciption](#cancel-subscription)
16- [Cancel Subsciption](#cancel-subscription)
17
17
18## Introduction
18## Introduction
19
19
20−A `%warp` task looks like:
20+A `%warp` `task` looks like:
21
21
22```hoon
22```hoon
23[%warp wer=ship rif=riff] :: internal file req
23[%warp wer=ship rif=riff] :: internal file req
@@ -29,7 +29,7 @@ The `riff` part is the following structure:
29+$ riff [p=desk q=(unit rave)] :: request+desist
29+$ riff [p=desk q=(unit rave)] :: request+desist
30```
30```
31
31
32−The `desk` is the desk in question. The `(unit rave)` is null to cancel a subscription, otherwise the `rave` is:
32+ The `(unit rave)` is null to cancel a subscription, otherwise the `rave` is:
33
33
34```hoon
34```hoon
35+$ rave :: general request
35+$ rave :: general request
@@ -47,15 +47,15 @@ The `desk` is the desk in question. The `(unit rave)` is null to cancel a subscr
47
47
48We'll look at each of these in more detail later.
48We'll look at each of these in more detail later.
49
49
50−Clay responds to a `%mult` request with a sign containing a `%wris` tagged `gift:clay`, and the rest with a `%writ`.
50+Clay responds to a `%mult` request with a `sign` containing a `%wris` `gift`, and the rest with a `%writ` `gift`.
51
51
52−A `%wris` gift looks like:
52+A `%wris` `gift` looks like:
53
53
54```hoon
54```hoon
55[%wris p=[%da p=@da] q=(set (pair care path))] :: many changes
55[%wris p=[%da p=@da] q=(set (pair care path))] :: many changes
56```
56```
57
57
58−A `%writ` gift looks like:
58+A `%writ` `gift` looks like:
59
59
60```hoon
60```hoon
61[%writ p=riot] :: response
61[%writ p=riot] :: response
@@ -93,9 +93,9 @@ This is for reading a single file or directory immediately. The `mood` structure
93+$ mood [=care =case =path] :: request in desk
93+$ mood [=care =case =path] :: request in desk
94```
94```
95
95
96−The `care` is `%x`, `%y` or whatever else. This will determine what you can read and what type of data will be returned. See the type documentation and scry documentation for details on the various cares.
96+The `care` is `%x`, `%y` or whatever else. This will determine what you can read and what type of data will be returned. See the type documentation and scry documentation for details on the various `care`s.
97
97
98−The `case` specifies the desk revision and looks like:
98+The `case` specifies the `desk` revision and looks like:
99
99
100```hoon
100```hoon
101+$ case :: ship desk case spur
101+$ case :: ship desk case spur
@@ -155,7 +155,7 @@ You should see something like this as the output:
155]
155]
156```
156```
157
157
158−The `cage` in the `riot` contains the file's data due to our use of an `%x` care. It needn't be an `%x` though. If we change it to `%u`, for example, we'll get a `?` cage instead:
158+The `cage` in the `riot` contains the file's data due to our use of an `%x` `care`. It needn't be an `%x` though. If we change it to `%u`, for example, we'll get a `?` `cage` instead:
159
159
160```hoon
160```hoon
161> -read-file /gen/hood/hi/hoon
161> -read-file /gen/hood/hi/hoon
@@ -167,7 +167,7 @@ The `cage` in the `riot` contains the file's data due to our use of an `%x` care
167]
167]
168```
168```
169
169
170−Here's a breakdown of the task we sent:
170+Here's a breakdown of the `task` we sent:
171
171
172![read file diagram](https://pub.m.tinnus-napbus.xyz/read-file.png "read file diagram")
172![read file diagram](https://pub.m.tinnus-napbus.xyz/read-file.png "read file diagram")
173
173
@@ -179,7 +179,7 @@ Here's a breakdown of the task we sent:
179
179
180This subscribes to the next version of the specified file. The `mood` structure is the same as described in the `%sing` example.
180This subscribes to the next version of the specified file. The `mood` structure is the same as described in the `%sing` example.
181
181
182−If 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`.
182+If 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`.
183
183
184`sub-next.hoon`
184`sub-next.hoon`
185
185
@@ -208,7 +208,7 @@ If you subscribe to the current case of the desk, clay will not respond until th
208(pure:m !>(~))
208(pure:m !>(~))
209```
209```
210
210
211−This thread will subscribe to the next version of the file given as an argument. It will print the `riot` it gets back from clay and will also print a message saying whether the file's been deleted or changed.
211+This thread will subscribe to the next version of the file given as an argument. It will print the `riot` it gets back from Clay and will also print a message saying whether the file's been deleted or changed.
212
212
213Save this in `ted/sub-next.hoon`, `|commit %home` and run like:
213Save this in `ted/sub-next.hoon`, `|commit %home` and run like:
214
214
@@ -255,9 +255,9 @@ Here's a breakdown of the task we sent:
255[%mult =mool] :: next version of any
255[%mult =mool] :: next version of any
256```
256```
257
257
258−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.
258+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.
259
259
260−The behaviour with respect to requesting old cases is the same as explained in the [`%next`](#next) section above.
260+The behaviour with respect to requesting old `case`s is the same as explained in the [`%next`](#next) section above.
261
261
262The `mool` specified in the request is this structure:
262The `mool` specified in the request is this structure:
263
263
@@ -265,11 +265,11 @@ The `mool` specified in the request is this structure:
265+$ mool [=case paths=(set (pair care path))] :: requests in desk
265+$ mool [=case paths=(set (pair care path))] :: requests in desk
266```
266```
267
267
268−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.
268+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.
269
269
270Example:
270Example:
271
271
272−This thread will subscribe to `/foo/txt` with an `%x` care and `/bar/txt` with a `%u` care. It will print out the `%wris` it gets back from clay.
272+This thread will subscribe to `/foo/txt` with an `%x` `care` and `/bar/txt` with a `%u` `care`. It will print out the `%wris` it gets back from Clay.
273
273
274`sub-mult.hoon`
274`sub-mult.hoon`
275
275
@@ -305,7 +305,7 @@ Save the above to `ted/sub-mult.hoon`, `|commit %home` and run with `-sub-mult`.
305+ /~zod/home/151/bar/txt
305+ /~zod/home/151/bar/txt
306```
306```
307
307
308−You'll notice that, unlike a `%writ`, the `%wris` doesn't give you the data. It merely tells gives you the cares and paths of the files that changed. If you need to actually get the data, you can just scry or send a request for the files in question.
308+You'll notice that, unlike a `%writ`, the `%wris` doesn't give you the data. It merely tells you the `care`s and `path`s of the files that changed. If you need to actually get the data, you can just scry or send a request for the files in question.
309
309
310Now, run the thread again, open `bar.txt` in an editor, modify its contents, save it and `|commit %home`. You'll notice you didn't receive a `%wris`. This is because we subscribed to `/bar/txt` with `%u` care and its existence didn't change.
310Now, run the thread again, open `bar.txt` in an editor, modify its contents, save it and `|commit %home`. You'll notice you didn't receive a `%wris`. This is because we subscribed to `/bar/txt` with `%u` care and its existence didn't change.
311
311
@@ -320,7 +320,7 @@ Lastly, delete `foo.txt` and `|commit %home`. You should see something like:
320
320
321As you can see, a relevant change to any of the subscribed files will trigger a response, not just when all of them change.
321As you can see, a relevant change to any of the subscribed files will trigger a response, not just when all of them change.
322
322
323−Here's a breakdown of the task we sent:
323+Here's a breakdown of the `task` we sent:
324
324
325![subscribe mult diagram](https://pub.m.tinnus-napbus.xyz/sub-mult.png "subscribe mult diagram")
325![subscribe mult diagram](https://pub.m.tinnus-napbus.xyz/sub-mult.png "subscribe mult diagram")
326
326
@@ -330,7 +330,7 @@ Here's a breakdown of the task we sent:
330[%many track=? =moat] :: track range
330[%many track=? =moat] :: track range
331```
331```
332
332
333−This subscribes to all changes to a desk for the specified range of cases. 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. It's basically what the system uses to keep in sync with a foreign desk. Regardless, we'll have a look at it for completeness.
333+This 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.
334
334
335If the `track` is `%.y` it will just return a `%writ` like:
335If the `track` is `%.y` it will just return a `%writ` like:
336
336
@@ -357,7 +357,7 @@ If the `track` is `%.n`, the `cage` of the `%writ` will contain a `nako`, which
357 == ::
357 == ::
358```
358```
359
359
360−As the comment explains, it contains all relevant data for a 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.
360+As the comment explains, it contains all relevant data for a 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.
361
361
362The `moat` in the `%many` is the following structure:
362The `moat` in the `%many` is the following structure:
363
363
@@ -365,11 +365,11 @@ The `moat` in the `%many` is the following structure:
365 +$ moat [from=case to=case =path] :: change range
365 +$ moat [from=case to=case =path] :: change range
366```
366```
367
367
368−The `from` and `to` fields specify the range of cases for which to subscribe. The range is *inclusive*. It can be specified by date or by revision number, whichever you prefer.
368+The `from` and `to` fields 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.
369
369
370−The `path` 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 send you nothing.
370+The `path` 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.
371
371
372−When you reach the end of the subscribed range of cases, clay will send you a `%writ` with a null `riot` to inform you the subscription has ended like:
372+When you reach the end of the subscribed range of `case`s, Clay will send you a `%writ` with a null `riot` to inform you the subscription has ended like:
373
373
374```hoon
374```hoon
375[%writ p=~]
375[%writ p=~]
@@ -377,7 +377,7 @@ When you reach the end of the subscribed range of cases, clay will send you a `%
377
377
378Example:
378Example:
379
379
380−This thread will subscribe to changes to your `%home` desk for the next three minutes. The `track` is `%.y` so it will only inform you of changes, not send the full `nako`. It will only get updates if the specified file exists. It contains a `main-loop` that will take an arbitrary number of signs and print them out in the dojo. Since it never ends, you'll need to stop it with the `:spider|kill` command in the dojo.
380+This thread will subscribe to changes to your `%home` `desk` for the next three minutes. The `track` is `%.y` so it will only inform you of changes, not send the full `nako`. It will only get updates if the specified file exists. It contains a `main-loop` that will take an arbitrary number of `sign`s and print them out in the dojo. Since it never ends, you'll need to stop it with the `:spider|kill` command in the dojo.
381
381
382`sub-many.hoon`
382`sub-many.hoon`
383
383
@@ -415,7 +415,7 @@ This thread will subscribe to changes to your `%home` desk for the next three mi
415(pure:m !>(~))
415(pure:m !>(~))
416```
416```
417
417
418−Make sure `foo.txt` doesn't exist in the root of your `%home` desk. Save this to `ted/sub-many.hoon`, `|commit %home`, run it like `-sub-many /foo/txt`, and hit backspace in the dojo to free up the dojo prompt. Now, add a file called `bar.txt` to your desk and `|commit %home`. You should see something like:
418+Make sure `foo.txt` doesn't exist in the root of your `%home` `desk`. Save this to `ted/sub-many.hoon`, `|commit %home`, run it like `-sub-many /foo/txt`, and hit backspace in the dojo to free up the dojo prompt. Now, add a file called `bar.txt` to your `desk` and `|commit %home`. You should see something like:
419
419
420```hoon
420```hoon
421> |commit %home
421> |commit %home
@@ -423,7 +423,7 @@ Make sure `foo.txt` doesn't exist in the root of your `%home` desk. Save this to
423+ /~zod/home/260/bar/txt
423+ /~zod/home/260/bar/txt
424```
424```
425
425
426−Notice you've received no `%writ` from clay. This is because `/foo/txt` doesn't exist. Now, create `foo.txt` and `|commit %home` again. You should see:
426+Notice you've received no `%writ` from Clay. This is because `/foo/txt` doesn't exist. Now, create `foo.txt` and `|commit %home` again. You should see:
427
427
428```hoon
428```hoon
429> |commit %home
429> |commit %home
@@ -459,7 +459,7 @@ Now wait until the three minutes is up and try making a change, for example dele
459- /~zod/home/263/baz/txt
459- /~zod/home/263/baz/txt
460```
460```
461
461
462−You can see that along with the normal `%writ` it's also sent a second `%writ` with a null `riot` to indicate the subscription has ended. This is because it has now passed the end of the range of cases to which you subscribed.
462+You can see that along with the normal `%writ` it's also sent a second `%writ` with a null `riot` to indicate the subscription has ended. This is because it has now passed the end of the range of `case`s to which you subscribed.
463
463
464Run `:spider|kill` to stop the thread.
464Run `:spider|kill` to stop the thread.
465
465
@@ -497,7 +497,7 @@ This thread will subscribe to the `%next` version of `/foo/txt`, then immediatel
497(pure:m !>(~))
497(pure:m !>(~))
498```
498```
499
499
500−Save the above to `ted/stop-sub.hoon`, `|commit %home`, run it with `-stop-sub` and hit backspace to detach it from the dojo prompt. Now, add `foo.txt` to the root of your `%home` desk and `|commit %home`. You should see:
500+Save the above to `ted/stop-sub.hoon`, `|commit %home`, run it with `-stop-sub` and hit backspace to detach it from the dojo prompt. Now, add `foo.txt` to the root of your `%home` `desk` and `|commit %home`. You should see:
501
501
502```hoon
502```hoon
503> |commit %home
503> |commit %home
@@ -509,6 +509,6 @@ As you can see we've received no `%writ`. We can thus conclude the subscription
509
509
510Run `:spider|kill` to stop the thread.
510Run `:spider|kill` to stop the thread.
511
511
512−Here's a breakdown of the task we sent:
512+Here's a breakdown of the `task` we sent:
513
513
514![cancel subscription diagram](https://pub.m.tinnus-napbus.xyz/stop-sub.png "cancel subscription diagram")
514![cancel subscription diagram](https://pub.m.tinnus-napbus.xyz/stop-sub.png "cancel subscription diagram")
arvo/clay/scry.md+26−24
@@ -4,7 +4,7 @@ weight = 5
4template = "doc.html"
4template = "doc.html"
5+++
5+++
6
6
7−The various clay scries are specified by a `care`, which is a single character that corresponds with a clay submodule. Apart from `%s` they just take a path to a desk, file or directory. All examples are dojo commands, the ='s in the path are automatically populated by the dojo like:
7+The various Clay scries are specified by a `care`, which is a single character corresponding with a Clay submodule. Apart from `%s` they just take a `path` to a `desk`, file or directory. All examples are dojo commands, the ='s in the path are automatically populated by the dojo like:
8
8
9```hoon
9```hoon
10> /===
10> /===
@@ -39,7 +39,7 @@ The various clay scries are specified by a `care`, which is a single character t
39
39
40## a
40## a
41
41
42−A scry with a care of `%a` will build a hoon file and return it as a `vase`.
42+A scry with a `care` of `%a` will build a `hoon` file and return it as a `vase`.
43
43
44Example:
44Example:
45
45
@@ -49,7 +49,7 @@ Example:
49
49
50## b
50## b
51
51
52−A scry with a care of `%b` will produce a `dais:clay` processed mark core for the specified mark. The `path` in the scry is a `mark`.
52+A scry with a `care` of `%b` will produce a `dais:clay` processed `mark` core for the specified `mark`. The `path` in the scry is a `mark`.
53
53
54Example:
54Example:
55
55
@@ -59,7 +59,7 @@ Example:
59
59
60## c
60## c
61
61
62−A scry with a care of `%c` will produce a `tube:clay` dynamically typed mark conversion gate. The `path` specifies two marks - *from* and *to*, like `/txt/noun`.
62+A scry with a `care` of `%c` will produce a `tube:clay` dynamically typed `mark` conversion gate. The `path` specifies two `mark`s - *from* and *to*, like `/txt/noun`.
63
63
64Example:
64Example:
65
65
@@ -71,7 +71,7 @@ Example:
71
71
72## d
72## d
73
73
74−A scry with a care of `%d` will return a `(set desk)` of the desks that exist on your ship.
74+A scry with a `care` of `%d` will return a `(set desk)` of the `desk`s that exist on your ship.
75
75
76Example:
76Example:
77
77
@@ -82,7 +82,7 @@ Example:
82
82
83## e
83## e
84
84
85−A scry with a care of `%e` will return a statically typed `nave:clay` mark core in a `vase`. The `path` in the scry specifies the `mark`.
85+A scry with a `care` of `%e` will return a statically typed `nave:clay` `mark` core in a `vase`. The `path` in the scry specifies the `mark`.
86
86
87Example:
87Example:
88
88
@@ -92,7 +92,7 @@ Example:
92
92
93## f
93## f
94
94
95−A scry with a care of `%f` will return a static mark conversion gate. The `path` specifies two marks - *from* and *to*, like `/txt/mime`.
95+A scry with a `care` of `%f` will return a static `mark` conversion gate. The `path` specifies two `mark`s - *from* and *to*, like `/txt/mime`.
96
96
97```hoon
97```hoon
98> =a .^($-(text mime) %cf /===/txt/mime)
98> =a .^($-(text mime) %cf /===/txt/mime)
@@ -102,7 +102,7 @@ A scry with a care of `%f` will return a static mark conversion gate. The `path`
102
102
103## p
103## p
104
104
105−A scry with a care of `%p` will return the permissions of the file or directory in question. The type returned is a `[dict:clay dict:clay]` where the head is read permissions and the tail is write permissions.
105+A scry with a `care` of `%p` will return the permissions of the file or directory in question. The type returned is a `[dict:clay dict:clay]` where the head is read permissions and the tail is write permissions.
106
106
107A `dict` is:
107A `dict` is:
108
108
@@ -124,7 +124,7 @@ A `dict` is:
124- `mod` specifies either a **black**list or a **white**list.
124- `mod` specifies either a **black**list or a **white**list.
125- `who` specifies:
125- `who` specifies:
126 - the set of allowed/disallowed ships.
126 - the set of allowed/disallowed ships.
127− - allowed/disallowed named crews (a crew is just a set of ships) - basically groups.
127+ - allowed/disallowed named `crew`s (a `crew` is just a `set` of ships) - basically groups.
128
128
129If the specified file or directory has no permissions set, it will default to the permissions of its parent. If nothing above it has permissions set, it will default to empty whitelists. If the specified file or directory doesn't exist, it will also return the default empty whitelist.
129If the specified file or directory has no permissions set, it will default to the permissions of its parent. If nothing above it has permissions set, it will default to empty whitelists. If the specified file or directory doesn't exist, it will also return the default empty whitelist.
130
130
@@ -137,7 +137,7 @@ Example:
137
137
138## r
138## r
139
139
140−A scry with a care of `%r` will return the data of the given file wrapped in a vase or crash if it's a directory. It's basically just a vase-wrapped `x`.
140+A scry with a `care` of `%r` will return the data of the given file wrapped in a `vase` or crash if it's a directory. It's basically just a vase-wrapped `%x` scry.
141
141
142Examples:
142Examples:
143
143
@@ -161,7 +161,9 @@ Crash!
161
161
162## s
162## s
163
163
164+A scry with a `care` of `%s` is for miscellaneous internal and debug functions and is liable to change in the future.
165+
164−A scry with a care of `%s` is more complex than the rest. Rather than just a path to a file, the path has a head of one of `%yaki %blob %hash %cage %open %late %base`. The rest of the path will depend on which of these tags you use. We'll look at each in turn. Note that `%s` is miscellaneous internal and debug functions and is liable to change in the future.
166+Rather than just a `path` to a file, the head of the `path` is tagged with one of `%yaki %blob %hash %cage %open %late %base` and the tail depends on which tag you use. We'll look at each in turn.
165
167
166### yaki
168### yaki
167
169
@@ -250,11 +252,11 @@ Here we grab the `lobe:clay` of `/gen/hood/hi/hoon` with a `%y` scry, then use i
250
252
251### open
253### open
252
254
253−This is like an `%a` scry but it only compiles the prelude to the file, eg. the ford rune imports. Proper documentation for this will be done as part of ford documentaton at a later date.
255+This is like a `%a` scry but it only compiles the prelude to the file, e.g. the Ford rune imports. Proper documentation for this will be done as part of Ford documentaton at a later date.
254
256
255### late
257### late
256
258
257−This will return the most recent revision number of a desk that has been fully downloaded. The type it returns is a `cass:clay`. The case in the `beak` must be a revision number rather than a date. You can just provide a case of `1` since it returns the latest regardless. If we have nothing for the specified desk, this will just return the bunt of a `cass:clay` like `cass=[ud=0 da=~2000.1.1]`
259+This will return the most recent revision number of a `desk` that has been fully downloaded. The type it returns is a `cass:clay`. The `case` in the `beak` must be a revision number rather than a date. You can just provide a case of `1` since it returns the latest regardless. If we have nothing for the specified `desk`, this will just return the bunt of a `cass:clay` like `cass=[ud=0 da=~2000.1.1]`.
258
260
259Example:
261Example:
260
262
@@ -270,7 +272,7 @@ cass=[ud=0 da=~2000.1.1]
270
272
271### base
273### base
272
274
273−This will return the mergebase (i.e. most recent common ancestor) between two desks. The type it returns is a `(list tako:clay)`. The first desk will just be the one in the `beak` path prefix and the second will be specified like `/ship/desk` at the end of the scry path. If there is no common ancestor between the two desks, this will just produce an empty list.
275+This will return the mergebase (i.e. most recent common ancestor) between two `desk`s. The type it returns is a `(list tako:clay)`. The first `desk` will just be the one in the `beak` `path` prefix and the second will be specified like `/ship/desk` at the end of the scry `path`. If there is no common ancestor between the two `desk`s, this will just produce an empty `list`.
274
276
275Examples:
277Examples:
276
278
@@ -286,7 +288,7 @@ Examples:
286
288
287## t
289## t
288
290
289−A scry with a care of `%t` will return a `(list path)` of all files in the given directory, or just a `(list path)` of the single file if it's a file. This is done recursively so will provide files in sub-directories as well. The paths will be fully qualified except for the ship, desk and case. If the directory or file specified does not exist, it will return null.
291+A scry with a `care` of `%t` will return a `(list path)` of all files in the given directory, or just a `(list path)` of the single file if it's a file. This is done recursively so will provide files in subdirectories as well. The paths will be fully qualified except for the `ship`, `desk` and `case`. If the directory or file specified does not exist, it will return an empty `list`.
290
292
291Examples:
293Examples:
292
294
@@ -314,7 +316,7 @@ Examples:
314
316
315## u
317## u
316
318
317−A scry with a care of `%u` will return a `?` depending on whether the file exists. It will produce `%.n` if it's a directory or doesn't exist and will produce `%.y` if it's a file and exists.
319+A scry with a `care` of `%u` will return a `?` depending on whether the file exists. It will produce `%.n` if it's a directory or doesn't exist and will produce `%.y` if it's a file and exists.
318
320
319Examples:
321Examples:
320
322
@@ -335,7 +337,7 @@ Examples:
335
337
336## v
338## v
337
339
338−A scry with a care of `%v` will return the entire state of a desk as a `dome:clay`.
340+A scry with a care of `%v` will return the entire state of a `desk` as a `dome:clay`.
339
341
340Example:
342Example:
341
343
@@ -345,11 +347,11 @@ Example:
3451
3471
346```
348```
347
349
348−If you try printing this it will take forever and probably OOM your ship.
350+Note: If you try printing this it will take forever and probably OOM your ship.
349
351
350## w
352## w
351
353
352−A scry with a care of `%w` will return the revision number and date of a given case. The type returned is a `cass:clay` like `[ud=@ud da=@da]` where `ud` is the revision number and `da` is the date.
354+A scry with a `care` of `%w` will return the revision number and date of a given `case`. The type returned is a `cass:clay` like `[ud=@ud da=@da]` where `ud` is the revision number and `da` is the date.
353
355
354Example:
356Example:
355
357
@@ -360,7 +362,7 @@ Example:
360
362
361## x
363## x
362
364
363−A scry with a care of `%x` will return the raw data of a file as an `@` or crash if it's a directory.
365+A scry with a `care` of `%x` will return the raw data of a file as an `@` or crash if it's a directory.
364
366
365
367
366Examples:
368Examples:
@@ -382,11 +384,11 @@ Crash!
382
384
383## y
385## y
384
386
385−A scry with a care of `%y` will return the `arch` of a file or directory.
387+A scry with a `care` of `%y` will return the `arch` of a file or directory.
386
388
387−An `arch` is a `[fil=(unit lobe:clay) dir=(map @ta ~)]`. The `fil` will contain the `lobe:clay` hash if it's a file, otherwise will be null. The `dir` will contain a map of the files and directories it contains, otherwise will be null.
389+An `arch` is a `[fil=(unit lobe:clay) dir=(map @ta ~)]`. The `fil` will contain the `lobe:clay` hash if it's a file, otherwise it will be null. The `dir` will contain a map of the files and directories it contains, otherwise it will be null.
388
390
389−It will return the bunt of an arch—`[fil=~ dir={}]`—if the file or directory is not found.
391+It will return the bunt of an `arch` if the file or directory is not found.
390
392
391Examples:
393Examples:
392
394
@@ -423,7 +425,7 @@ Examples:
423
425
424## z
426## z
425
427
426−A scry with a care of `%z` will return the hash of a file or the recursive hash of a directory. If the file or directory doesn't exist it will return a null value.
428+A scry with a `care` of `%z` will return the hash of a file or the recursive hash of a directory. If the file or directory doesn't exist it will return a null value.
427
429
428The type returned is a `@uxI`.
430The type returned is a `@uxI`.
429
431
arvo/clay/write.md+8−8
@@ -4,7 +4,7 @@ weight = 7
4template = "doc.html"
4template = "doc.html"
5+++
5+++
6
6
7−Here we'll look at creating, changing and deleting files by passing clay an `%info` tagged `task:clay`.
7+Here we'll look at creating, changing and deleting files by passing Clay an `%info` `task`.
8
8
9## Contents
9## Contents
10
10
@@ -16,7 +16,7 @@ Here we'll look at creating, changing and deleting files by passing clay an `%in
16
16
17## Introduction
17## Introduction
18
18
19−An `%info` task looks like:
19+An `%info` `task` looks like:
20
20
21```hoon
21```hoon
22[%info des=desk dit=nori] :: internal edit
22[%info des=desk dit=nori] :: internal edit
@@ -48,10 +48,10 @@ This is just a list of changes so you can make more than one change in one reque
48
48
49- `%del` - Delete a file.
49- `%del` - Delete a file.
50- `%ins` - Insert file. This will also replace an existing file.
50- `%ins` - Insert file. This will also replace an existing file.
51−- `%dif` - this has not yet been implemented so will crash with a `%dif-not-implemented` error.
51+- `%dif` - This has not yet been implemented so will crash with a `%dif-not-implemented` error.
52- `%mut` - Change a file. At the time of writing this behaves identically to `%ins` so its use merely informs the reader.
52- `%mut` - Change a file. At the time of writing this behaves identically to `%ins` so its use merely informs the reader.
53
53
54−Clay does not give any response to an `%info` task so don't expect a sign back.
54+Clay does not give any response to an `%info` `task` so don't expect a `sign` back.
55
55
56Now we'll look at some example threads:
56Now we'll look at some example threads:
57
57
@@ -87,9 +87,9 @@ Save it in `/ted/add-file.hoon`, `|commit %home` and run it like:
87
87
88If you have a look in the home of your pier you'll see there's now a file called `foo.txt` with the text `foo` in it.
88If you have a look in the home of your pier you'll see there's now a file called `foo.txt` with the text `foo` in it.
89
89
90−We've created the cage of the content like `[%txt !>(wain)]`, if you want to write something besides a text file you'd just give it the appropriate mark and vase.
90+We've created the `cage` of the content like `[%txt !>(wain)]`, if you want to write something besides a text file you'd just give it the appropriate `mark` and `vase`.
91
91
92−Here's a breakdown of the `task:clay` we sent:
92+Here's a breakdown of the `task` we sent:
93
93
94![write file diagram](https://pub.m.tinnus-napbus.xyz/write-file-diagram.png)
94![write file diagram](https://pub.m.tinnus-napbus.xyz/write-file-diagram.png)
95
95
@@ -124,7 +124,7 @@ Save the above code in `ted/delete-file.hoon`, `|commit %home` and run it like:
124
124
125If you have a look in the home of your pier you'll see the `foo.txt` file you created is now gone.
125If you have a look in the home of your pier you'll see the `foo.txt` file you created is now gone.
126
126
127−Here's a breakdown of the `task:clay` we sent:
127+Here's a breakdown of the `task` we sent:
128
128
129![delete file diagram](https://pub.m.tinnus-napbus.xyz/delete-file-diagram.png)
129![delete file diagram](https://pub.m.tinnus-napbus.xyz/delete-file-diagram.png)
130
130
@@ -134,7 +134,7 @@ Identical to the [Add File](#add-file) example, just replace `%ins` with `%mut`.
134
134
135## Multiple Changes
135## Multiple Changes
136
136
137−Since `soba:clay` is just a `list` of `miso:clay`, you can add a bunch of `miso:clay` and they'll all be applied. This thread adds three files and then deletes them. Here there's only one type of `miso` in each request but you could mix different types together too.
137+Since `soba` is just a `list` of `miso`, you can add a bunch of `miso` and they'll all be applied. This thread adds three files and then deletes them. Here there's only one type of `miso` in each request but you could mix different types together too.
138
138
139`multi-change.hoon`
139`multi-change.hoon`
140
140