git.iko.soy/urbit.org
on master help sign in
Add writing files doc
602fb98tinnus-napbus
arvo/clay/_index.md+4
compare with master
unifiedsplit
@@ -30,3 +30,7 @@ Reference for Clay's various scry endpoints.
30[Read and Subscribe](@/docs/arvo/clay/read.md)
30[Read and Subscribe](@/docs/arvo/clay/read.md)
31
31
32How to read files and subscribe for changes.
32How to read files and subscribe for changes.
33+
34+[Write and Modify](@/docs/arvo/clay/write.md)
35+
36+How to add, delete and modify files.
arvo/clay/clay.md+4
@@ -59,3 +59,7 @@ Reference for Clay's various scry endpoints.
59[Read and Subscribe](@/docs/arvo/clay/read.md)
59[Read and Subscribe](@/docs/arvo/clay/read.md)
60
60
61How to read files and subscribe for changes.
61How to read files and subscribe for changes.
62+
63+[Write and Modify](@/docs/arvo/clay/write.md)
64+
65+How to add, delete and modify files.
arvo/clay/write.mdnew file+172
@@ -0,0 +1,172 @@
1++++
2+title = "Write and Modify"
3+weight = 7
4+template = "doc.html"
5++++
6+
7+Here we'll look at creating, changing and deleting files by passing clay an `%info` tagged `task:clay`.
8+
9+## Contents
10+
11+- [Introduction](#introduction)
12+- [Add File](#add-file)
13+- [Delete File](#delete-file)
14+- [Mutate File](#mutate-file)
15+- [Multiple Changes](#multiple-changes)
16+
17+## Introduction
18+
19+An `%info` task looks like:
20+
21+```hoon
22+[%info des=desk dit=nori] :: internal edit
23+```
24+
25+While the `desk` part is self-evident, the `nori` part is the following structure:
26+
27+```hoon
28++$ nori :: repository action
29+ $% [%& p=soba] :: delta
30+ [%| p=@tas] :: label
31+```
32+
33+The `%|` tag is not currently supported and will crash with a `%labelling-not-implemented` if used, so we can focus on the `%&` part. A `soba` is the following structure:
34+
35+```hoon
36++$ soba (list [p=path q=miso]) :: delta
37+```
38+
39+This is just a list of changes so you can make more than one change in one request. The `path` is just the path to a file like `/gen/hood/hi/hoon` and the `miso` is the following structure:
40+
41+```hoon
42++$ miso :: ankh delta
43+ $% [%del ~] :: delete
44+ [%ins p=cage] :: insert
45+ [%dif p=cage] :: mutate from diff
46+ [%mut p=cage] :: mutate from raw
47+```
48+
49+- `%del` - Delete a 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.
52+- `%mut` - Change a file. At the time of writing this behaves identically to `%ins` so its use merely informs the reader.
53+
54+Clay does not give any response to an `%info` task so don't expect a sign back.
55+
56+Now we'll look at some example threads:
57+
58+## Add File
59+
60+**`add-file.hoon`**
61+
62+```hoon
63+/- spider
64+/+ strandio
65+=, strand=strand:spider
66+^- thread:spider
67+|= arg=vase
68+=/ m (strand ,vase)
69+^- form:m
70+=/ uarg !< (unit (pair path @t)) arg
71+?~ uarg
72+ (strand-fail:strand %no-arg ~)
73+=/ =path p.u.uarg
74+=/ =wain [q.u.uarg ~]
75+=/ =task:clay [%info %home %& [[path %ins %txt !>(wain)] ~]]
76+=/ =card:agent:gall [%pass /info %arvo %c task]
77+;< ~ bind:m (send-raw-card:strandio card)
78+(pure:m !>(~))
79+```
80+
81+Save it in `/ted/add-file.hoon`, `|commit %home` and run it like:
82+
83+```hoon
84+> -add-file /foo/txt 'foo'
85++ /~zod/home/22/foo/txt
86+```
87+
88+If 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+
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+
92+Here's a breakdown of the `task:clay` we sent:
93+
94+![write file diagram](https://pub.m.tinnus-napbus.xyz/write-file-diagram.png)
95+
96+## Delete File
97+
98+**`delete-file.hoon`**
99+
100+```hoon
101+/- spider
102+/+ strandio
103+=, strand=strand:spider
104+^- thread:spider
105+|= arg=vase
106+=/ m (strand ,vase)
107+^- form:m
108+=/ uarg !< (unit path) arg
109+?~ uarg
110+ (strand-fail:strand %no-arg ~)
111+=/ =path u.uarg
112+=/ =task:clay [%info %home %& [path %del ~] ~]
113+=/ =card:agent:gall [%pass /info %arvo %c task]
114+;< ~ bind:m (send-raw-card:strandio card)
115+(pure:m !>(~))
116+```
117+
118+Save the above code in `ted/delete-file.hoon`, `|commit %home` and run it like:
119+
120+```hoon
121+> -delete-file /foo/txt
122+- /~zod/home/24/foo/txt
123+```
124+
125+If you have a look in the home of your pier you'll see the `foo.txt` file you created is now gone.
126+
127+Here's a breakdown of the `task:clay` we sent:
128+
129+![delete file diagram](https://pub.m.tinnus-napbus.xyz/delete-file-diagram.png)
130+
131+## Mutate File
132+
133+Identical to the [Add File](#add-file) example, just replace `%ins` with `%mut`.
134+
135+## Multiple Changes
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.
138+
139+**`multi-change.hoon`**
140+
141+```hoon
142+/- spider
143+/+ strandio
144+=, strand=strand:spider
145+^- thread:spider
146+|= arg=vase
147+=/ m (strand ,vase)
148+^- form:m
149+=/ soba-a :~ [/foo/txt %ins %txt !>(['foo' ~])]
150+ [/bar/txt %ins %txt !>(['bar' ~])]
151+ [/baz/txt %ins %txt !>(['baz' ~])]
152+ ==
153+=/ soba-b :~ [/foo/txt %del ~]
154+ [/bar/txt %del ~]
155+ [/baz/txt %del ~]
156+ ==
157+;< ~ bind:m (send-raw-card:strandio [%pass /info %arvo %c %info %home %& soba-a])
158+;< ~ bind:m (send-raw-card:strandio [%pass /info %arvo %c %info %home %& soba-b])
159+(pure:m !>(~))
160+```
161+
162+Save to `ted/multi-change.hoon`, `|commit %home`, and run:
163+
164+```hoon
165+> -multi-change
166++ /~zod/home/37/foo/txt
167++ /~zod/home/37/bar/txt
168++ /~zod/home/37/baz/txt
169+- /~zod/home/38/foo/txt
170+- /~zod/home/38/bar/txt
171+- /~zod/home/38/baz/txt
172+```