@@ -0,0 +1,445 @@
1++++
2+title = "Scry Reference"
3+weight = 5
4+template = "doc.html"
5++++
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:
8+
9+```hoon
10+> /===
11+[~.~zod ~.home ~.~2021.4.26..02.29.03..d31b ~]
12+```
13+
14+## Contents
15+
16+- [`a`](#a) - Build a hoon file.
17+- [`b`](#b) - Dynamic mark.
18+- [`c`](#c) - Dynamic mark conversion.
19+- [`d`](#d) - List desks.
20+- [`e`](#e) - Static mark.
21+- [`f`](#f) - Static mark conversion.
22+- [`p`](#p) - File permissions.
23+- [`r`](#r) - Vase-wrapped file data.
24+- [`s`](#s) - Miscellaneous scries:
25+ - [`yaki`](#yaki) - `yaki:clay` of the specified commit.
26+ - [`blob`](#blob) - `blob:clay` of file.
27+ - [`hash`](#hash) - Content hash of the specified commit.
28+ - [`cage`](#cage) - `cage` of the data of a file.
29+ - [`open`](#open) - Compile prelude of file.
30+ - [`late`](#late) - Most recent case of desk.
31+ - [`base`](#base) - Mergebase of two desks.
32+- [`t`](#t) - List files in directory.
33+- [`u`](#u) - Check for existence of file.
34+- [`v`](#v) - Desk state.
35+- [`w`](#w) - Revision number of the given desk case.
36+- [`x`](#x) - Raw data of file.
37+- [`y`](#y) - `arch` of a file or directory.
38+- [`z`](#z) - Content hash of a file or directory.
39+
40+## a
41+
42+A scry with a care of `%a` will build a hoon file and return it as a `vase`.
43+
44+Example:
45+
46+```hoon
47+.^(vase %ca /===/lib/strandio/hoon)
48+```
49+
50+## b
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`.
53+
54+Example:
55+
56+```hoon
57+.^(dais:clay %cb /===/txt)
58+```
59+
60+## c
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`.
63+
64+Example:
65+
66+```hoon
67+> =a .^(tube:clay %cc /===/txt/mime)
68+> !< mime (a !>(~['foo']))
69+[p=/text/plain q=[p=3 q=7.303.014]]
70+```
71+
72+## d
73+
74+A scry with a care of `%d` will return a `(set desk)` of the desks that exist on your ship.
75+
76+Example:
77+
78+```hoon
79+> .^((set desk) %cd /===)
80+{%home %kids}
81+```
82+
83+## e
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`.
86+
87+Example:
88+
89+```hoon
90+.^(vase %ce /===/noun)
91+```
92+
93+## f
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`.
96+
97+```hoon
98+> =a .^($-(text mime) %cf /===/txt/mime)
99+> (a ~['foo'])
100+[p=/text/plain q=[p=3 q=7.303.014]]
101+```
102+
103+## p
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.
106+
107+A `dict` is:
108+
109+```hoon
110++$ dict [src=path rul=real]
111+```
112+
113+...and a `real` is:
114+
115+```hoon
116++$ real
117+ $: mod=?(%black %white)
118+ who=(pair (set ship) (map @ta crew))
119+ ==
120+```
121+
122+...where:
123+
124+- `mod` specifies either a **black**list or a **white**list.
125+- `who` specifies:
126+ - the set of allowed/disallowed ships.
127+ - allowed/disallowed named crews (a crew is just a set of ships) - basically groups.
128+
129+If 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+
131+Example:
132+
133+```hoon
134+> .^([dict:clay dict:clay] %cp /===/gen)
135+[[src=/ rul=[mod=%white who=[p={} q={}]]] src=/ rul=[mod=%white who=[p={} q={}]]]
136+```
137+
138+## r
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`.
141+
142+Examples:
143+
144+```hoon
145+> .^(vase %cr /===/gen/hood/hi/hoon)
146+[ #t/@
147+ q
148+ 3.548.750.706.400.251.607.252.023.288.575.526.190.856.734.474.077.821.289.791.377.301.707.878.697.553.411.219.689.905.949.957.893.633.811.025.757.107.990.477.902.858.170.125.439.223.250.551.937.540.468.638.902.955.378.837.954.792.031.592.462.617.422.136.386.332.469.076.584.061.249.923.938.374.214.925.312.954.606.277.212.923.859.309.330.556.730.410.200.952.056.760.727.611.447.500.996.168.035.027.753.417.869.213.425.113.257.514.474.700.810.203.348.784.547.006.707.150.406.298.809.062.567.217.447.347.357.039.994.339.342.906
149+]
150+```
151+
152+```hoon
153+> !< @t .^(vase %cr /===/gen/hood/hi/hoon)
154+':: Helm: send message to an urbit\0a::\0a:::: /hoon/hi/hood/gen\0a ::\0a/? 310\0a:- %say\0a|=([^ [who=ship mez=$@(~ [a=tape ~])] ~] helm-send-hi+[who ?~(mez ~ `a.mez)])\0a'
155+```
156+
157+```hoon
158+> .^(vase %cr /===/gen)
159+Crash!
160+```
161+
162+## s
163+
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.
165+
166+### yaki
167+
168+This will return the `yaki:clay` of the specified commit. It takes a `tako:clay`.
169+
170+Example:
171+
172+Here we scry the `dome:clay` for `/===`, get the latest `tako:clay` and the do a `%s` scry for the `yaki:clay` in question.
173+
174+```hoon
175+> =/ =dome:clay .^(dome:clay %cv /===)
176+ =/ =tako:clay (~(got by hit.dome) let.dome)
177+ .^(yaki:clay %cs /===/yaki/(scot %uv tako))
178+[ p=~[80.174.473.756.485.530.520.259.753.935.584.637.641.665.425.899.348.092.348.244.635.557.986.495.151.006]
179+ q
180+ { [p=/mar/hark/graph-hook-update/hoon q=0v5.ea0bj.21s5c.mjrop.ishic.fpkvl.e5bbs.91kc9.tdo41.ifi06.60v41]
181+ [p=/gen/hood/autocommit/hoon q=0v19.rh7jv.sa67o.t3jrb.4sdvs.7c45f.pv2u0.ragik.psp20.agqd8.8srkj]
182+ ...
183+ [p=/tests/lib/primitive-rsa/hoon q=0v1g.3qmq3.6i15q.arh6h.lfsqu.gvc9m.ql6m5.e2rdr.vnnt9.tptc6.mv9u7]
184+ [p=/tests/sys/vane/gall/hoon q=0va.alspc.qptqn.7tuj0.bgecg.1093t.gtsjs.up03k.d1fmk.4jrh8.2tdfa]
185+ }
186+ r=88.666.797.531.755.181.802.690.473.856.185.443.710.929.766.582.249.039.904.824.278.074.149.777.897.099
187+ t=~2021.4.16..10.41.57..3565
188+]
189+```
190+
191+### blob
192+
193+This will return the `blob:clay` of some file. It takes a `lobe:clay`.
194+
195+Example:
196+
197+Here we grab the `lobe:clay` of `/gen/hood/hi/hoon` with a `%y` scry, then use it to do a `%s` scry for the `blob:clay` of the file.
198+
199+```hoon
200+> =/ =arch .^(arch %cy /===/gen/hood/hi/hoon)
201+ ?~ fil.arch
202+ ~
203+ .^(blob:clay %cs /===/blob/(scot %uv u.fil.arch))
204+[ %direct
205+ p=0vp.k7nsm.qkdr3.t17rp.33bae.8gajg.v27gi.40itr.2u9qa.nppbt.7k255
206+ q
207+ [ p=%hoon
208+ q
209+3.548.750.706.400.251.607.252.023.288.575.526.190.856.734.474.077.821.289.791.377.301.707.878.697.553.411.219.689.905.949.957.893.633.811.025.757.107.990.477.902.858.170.125.439.223.250.551.937.540.468.638.902.955.378.837.954.792.031.592.462.617.422.136.386.332.469.076.584.061.249.923.938.374.214.925.312.954.606.277.212.923.859.309.330.556.730.410.200.952.056.760.727.611.447.500.996.168.035.027.753.417.869.213.425.113.257.514.474.700.810.203.348.784.547.006.707.150.406.298.809.062.567.217.447.347.357.039.994.339.342.906
210+ ]
211+]
212+```
213+
214+### hash
215+
216+This will return the `@uvI` content hash of the specified commit. It takes a `tako:clay`.
217+
218+Example:
219+
220+Here we grab the `dome:clay` for `/===` with a `%v` scry, get the latest `tako:clay` and then do a `%s` `%hash` scry for it.
221+
222+```hoon
223+> =/ =dome:clay .^(dome:clay %cv /===)
224+ =/ =tako:clay (~(got by hit.dome) let.dome)
225+ .^(tako:clay %cs /===/hash/(scot %uv tako))
226+0v16.er7uq.oke4u.cru7u.nglu9.q3su7.6ub1o.bh4qk.r5uav.ut12d.5rdl5
227+```
228+
229+### cage
230+
231+This will return a `cage` of the data of some file. It takes a `lobe:clay`.
232+
233+Example:
234+
235+Here we grab the `lobe:clay` of `/gen/hood/hi/hoon` with a `%y` scry, then use it to do a `%s` scry for the `cage` of the data.
236+
237+```hoon
238+> =/ =arch .^(arch %cy /===/gen/hood/hi/hoon)
239+ ?~ fil.arch
240+ ~
241+ .^(cage %cs /===/cage/(scot %uv u.fil.arch))
242+[ p=%hoon
243+ q
244+ [ #t/@t
245+ q
246+3.548.750.706.400.251.607.252.023.288.575.526.190.856.734.474.077.821.289.791.377.301.707.878.697.553.411.219.689.905.949.957.893.633.811.025.757.107.990.477.902.858.170.125.439.223.250.551.937.540.468.638.902.955.378.837.954.792.031.592.462.617.422.136.386.332.469.076.584.061.249.923.938.374.214.925.312.954.606.277.212.923.859.309.330.556.730.410.200.952.056.760.727.611.447.500.996.168.035.027.753.417.869.213.425.113.257.514.474.700.810.203.348.784.547.006.707.150.406.298.809.062.567.217.447.347.357.039.994.339.342.906
247+ ]
248+]
249+```
250+
251+### open
252+
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.
254+
255+### late
256+
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]`
258+
259+Example:
260+
261+```hoon
262+> .^(=cass:clay %cs /(scot %p (sein:title our now our))/kids/1/late)
263+cass=[ud=50 da=~2021.4.22..10.38.50..57a8]
264+```
265+
266+```hoon
267+> .^(=cass:clay %cs /~sampel/kids/1/late)
268+cass=[ud=0 da=~2000.1.1]
269+```
270+
271+### base
272+
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.
274+
275+Examples:
276+
277+```hoon
278+> .^((list tako:clay) %cs /===/base/(scot %p (sein:title our now our))/kids)
279+~[102.787.244.596.033.419.950.995.540.301.493.841.569.518.772.322.508.085.465.561.801.703.148.627.263.473]
280+```
281+
282+```hoon
283+> .^((list tako:clay) %cs /===/base/~sampel/kids)
284+~
285+```
286+
287+## t
288+
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.
290+
291+Examples:
292+
293+```hoon
294+> .^((list path) %ct /===/app/landscape)
295+~[
296+ /app/landscape/css/index/css
297+ /app/landscape/img/favicon/png
298+ /app/landscape/img/imageupload/png
299+ /app/landscape/img/touch_icon/png
300+ /app/landscape/index/html
301+ /app/landscape/js/channel/js
302+]
303+```
304+
305+```hoon
306+> .^((list path) %ct /===/gen/group-store/add/hoon)
307+~[/gen/group-store/add/hoon]
308+```
309+
310+```hoon
311+> .^((list path) %ct /===/foobar)
312+~
313+```
314+
315+## u
316+
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.
318+
319+Examples:
320+
321+```hoon
322+> .^(? %cu /===/app)
323+%.n
324+```
325+
326+```hoon
327+> .^(? %cu /===/gen/code/hoon)
328+%.y
329+```
330+
331+```hoon
332+> .^(? %cu /===/foobar)
333+%.n
334+```
335+
336+## v
337+
338+A scry with a care of `%v` will return the entire state of a desk as a `dome:clay`.
339+
340+Example:
341+
342+```hoon
343+> =a .^(dome:clay %cv /===)
344+> let.a
345+1
346+```
347+
348+If you try printing this it will take forever and probably OOM your ship.
349+
350+## w
351+
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.
353+
354+Example:
355+
356+```hoon
357+> .^(cass:clay %cw /===)
358+[ud=2 da=~2021.4.13..19.12.49..3389]
359+```
360+
361+## x
362+
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.
364+
365+
366+Examples:
367+
368+```hoon
369+> .^(@ %cx /===/gen/hood/hi/hoon)
370+3.548.750.706.400.251.607.252.023.288.575.526.190.856.734.474.077.821.289.791.377.301.707.878.697.553.411.219.689.905.949.957.893.633.811.025.757.107.990.477.902.858.170.125.439.223.250.551.937.540.468.638.902.955.378.837.954.792.031.592.462.617.422.136.386.332.469.076.584.061.249.923.938.374.214.925.312.954.606.277.212.923.859.309.330.556.730.410.200.952.056.760.727.611.447.500.996.168.035.027.753.417.869.213.425.113.257.514.474.700.810.203.348.784.547.006.707.150.406.298.809.062.567.217.447.347.357.039.994.339.342.906
371+```
372+
373+```hoon
374+> .^(@t %cx /===/gen/hood/hi/hoon)
375+':: Helm: send message to an urbit\0a::\0a:::: /hoon/hi/hood/gen\0a ::\0a/? 310\0a:- %say\0a|=([^ [who=ship mez=$@(~ [a=tape ~])] ~] helm-send-hi+[who ?~(mez ~ `a.mez)])\0a'
376+```
377+
378+```hoon
379+> .^(@ %cx /===/gen/hood)
380+Crash!
381+```
382+
383+## y
384+
385+A scry with a care of `%y` will return the `arch` of a file or directory.
386+
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.
388+
389+It will return the bunt of an arch—`[fil=~ dir={}]`—if the file or directory is not found.
390+
391+Examples:
392+
393+```hoon
394+> .^(arch %cy /===/gen/group-store)
395+[ fil=~
396+ dir
397+ { [p=~.allow-ships q=~]
398+ [p=~.add q=~]
399+ [p=~.ban-ranks q=~]
400+ [p=~.remove q=~]
401+ [p=~.create q=~]
402+ [p=~.join q=~]
403+ [p=~.allow-ranks q=~]
404+ [p=~.ban-ships q=~]
405+ }
406+]
407+```
408+
409+```hoon
410+> .^(arch %cy /===/gen/group-store/allow-ships)
411+[fil=~ dir={[p=~.hoon q=~]}]
412+```
413+
414+```hoon
415+> .^(arch %cy /===/gen/group-store/allow-ships/hoon)
416+[fil=[~ 0vb.g8sqs.7gjm9.bl3vu.nk677.h5be1.g9eg3.4v1jo.00ivf.g8ndu.48a53] dir={}]
417+```
418+
419+```hoon
420+> .^(arch %cy /===/foobar)
421+[fil=~ dir={}]
422+```
423+
424+## z
425+
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.
427+
428+The type returned is a `@uxI`.
429+
430+Examples:
431+
432+```hoon
433+> .^(@uvI %cz /===/gen)
434+0v5.itmhj.lt7ak.lgr1k.dr7vu.u7u9s.ko5rf.idfcr.ukrd2.t088n.3ml1k
435+```
436+
437+```hoon
438+> .^(@uvI %cz /===/gen/code/hoon)
439+0v1t.vi1pf.3ba4n.87g6h.dcc1p.4t4l8.rm6a9.b4de4.v77qc.p9dc0.p8289
440+```
441+
442+```hoon
443+> .^(@uvI %cz /===/foobar)
444+0v0
445+```