mirror of
https://github.com/urbit/developers.urbit.org.git
synced 2024-09-11 13:55:59 +03:00
Merge pull request #260 from urbit/update-clay-reference
update clay types, tasks and scry endpoints
This commit is contained in:
tinnus-napbus
GitHub
commit
0260d92f88
File diff suppressed because it is too large
Load Diff
@ -3,14 +3,148 @@ title = "Scry Reference"
|
||||
weight = 5
|
||||
+++
|
||||
|
||||
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:
|
||||
The normal 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:
|
||||
|
||||
```
|
||||
> %
|
||||
[~.~zod ~.base ~.~2021.4.26..02.29.03..d31b ~]
|
||||
```
|
||||
|
||||
## %a - Build hoon.
|
||||
In addition to the ordinary `care`-based endpoints, there are also a few special
|
||||
endpoints described in the [Misc. Queries](#misc-queries) section below.
|
||||
|
||||
## Misc. queries
|
||||
|
||||
Clay exposes a few special "buc" scry endpoints. These all use a `%x` `care` and
|
||||
must have a desk of `%$` (an empty string) in the `beak`. They therefore have
|
||||
the basic form of:
|
||||
|
||||
```
|
||||
.^([return type] %cx /=//=/[path])
|
||||
```
|
||||
|
||||
Each of the possible `[path]`s are described below.
|
||||
|
||||
---
|
||||
|
||||
### `/sweep` - Cache check
|
||||
|
||||
A buc scry with a path of `/sweep` will check the global ford cache for refcount
|
||||
errors. It returns a `(list [need=@ud have=@ud leak])`, where a
|
||||
[`leak`](/reference/arvo/clay/data-types#leak) is a Ford cache key used
|
||||
internally by Clay.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
> .^((list [need=@ud have=@ud *]) %cx /=//=/sweep)
|
||||
~
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/rang` - Get `rang`
|
||||
|
||||
A buc scry with a path of `/rang` will return the full
|
||||
[`rang`](/reference/arvo/clay/data-types#rangclay) from Clay's state.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
> =ran .^(rang:clay %cx /=//=/rang)
|
||||
> ~(wyt by hut.ran)
|
||||
31
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/tomb/[path]` - Is accessible?
|
||||
|
||||
A buc scry with a path beginning with `/tomb` will return a `?` which is `%.y`
|
||||
if the file specified by `[path]` is accessible, and `%.n` otherwise. The
|
||||
`[path]` must be a full `beam` like `/~zod/base/12/sys/kelvin`.
|
||||
|
||||
Note that `%.n` is returned either if the file has been tombstoned or if it
|
||||
doesn't exist at all, so it doubles as a tombstone check and existence check.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
> .^(? %cx /=//=/tomb/(scot %p our)/base/(scot %da now)/sys/kelvin)
|
||||
%.y
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/domes` - All domes
|
||||
|
||||
A buc scry with a path of `/domes` will return a
|
||||
[`cone:clay`](/reference/arvo/clay/data-types#coneclay) containing the `dome`s
|
||||
and associated metadata for all desks, foreign and local.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
> =domes .^(cone:clay %cx /=//=/domes)
|
||||
> ~(key by domes)
|
||||
{ [~zod %landscape]
|
||||
[~mister-dister-dozzod-dozzod %garden]
|
||||
[~lander-dister-dozzod-dozzod %landscape]
|
||||
[~mister-dister-dozzod-dozzod %webterm]
|
||||
[~zod %bitcoin]
|
||||
[~zod %kids]
|
||||
[~zod %garden]
|
||||
[~zod %base]
|
||||
[~zod %webterm]
|
||||
[~mister-dister-dozzod-dozzod %bitcoin]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/tire` - App state
|
||||
|
||||
A buc scry with a path of `/tire` will return the `rock:tire:clay` for all
|
||||
domestic desks, which is a `(map desk [=zest wic=(set weft)])`. The
|
||||
[`zest`](/reference/arvo/clay/data-types#zestclay) specifies whether apps on the
|
||||
desk are running or suspended. The `wic` set contains the `weft`s (kernel
|
||||
versions) of any queued updates.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
> .^(rock:tire:clay %cx /=//=/tire)
|
||||
{ [p=%bitcoin q=[zest=%live wic={}]]
|
||||
[p=%base q=[zest=%live wic={}]]
|
||||
[p=%landscape q=[zest=%live wic={}]]
|
||||
[p=%webterm q=[zest=%live wic={}]]
|
||||
[p=%garden q=[zest=%live wic={}]]
|
||||
[p=%kids q=[zest=%dead wic={}]]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `/tyre` - App state subs
|
||||
|
||||
A buc scry with a path of `/tyre` will return the `(set duct)` of all
|
||||
subscriptions to app states (those made via `%tire` tasks).
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
> .^((set duct) %cx /=//=/tyre)
|
||||
{ ~[/gall/use/hark-system-hook/0w2.k8ns8/~zod/clay/tire /dill //term/1]
|
||||
~[/gall/use/docket/0w2.k8ns8/~zod/tire /dill //term/1]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## `%a` - Build hoon
|
||||
|
||||
A scry with a `care` of `%a` will build a `hoon` file and return it as a `vase`.
|
||||
|
||||
@ -20,9 +154,12 @@ Example:
|
||||
.^(vase %ca %/lib/strandio/hoon)
|
||||
```
|
||||
|
||||
## %b - Dyn. mark core.
|
||||
---
|
||||
|
||||
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`.
|
||||
## `%b` - Dyn. mark core
|
||||
|
||||
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`.
|
||||
|
||||
Example:
|
||||
|
||||
@ -30,9 +167,11 @@ Example:
|
||||
.^(dais:clay %cb %/txt)
|
||||
```
|
||||
|
||||
## %c - Dyn. mark convert.
|
||||
## %c - Dyn. mark convert
|
||||
|
||||
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`.
|
||||
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`.
|
||||
|
||||
Example:
|
||||
|
||||
@ -42,9 +181,12 @@ Example:
|
||||
[p=/text/plain q=[p=3 q=7.303.014]]
|
||||
```
|
||||
|
||||
## %d - List desks.
|
||||
---
|
||||
|
||||
A scry with a `care` of `%d` will return a `(set desk)` of the `desk`s that exist on your ship.
|
||||
## `%d` - List desks
|
||||
|
||||
A scry with a `care` of `%d` will return a `(set desk)` of the `desk`s that
|
||||
exist on your ship.
|
||||
|
||||
Example:
|
||||
|
||||
@ -53,9 +195,14 @@ Example:
|
||||
{%bitcoin %base %landscape %webterm %garden %kids}
|
||||
```
|
||||
|
||||
## %e - Static mark core.
|
||||
---
|
||||
|
||||
A scry with a `care` of `%e` will return a statically typed `nave:clay` `mark` core. The `path` in the scry specifies the `mark`. The type returned is a `(nave:clay {type} {diff})`, where `{type}` is the type the `mark` takes and `{diff}` is the type taken by the `mark` specified in `+form:grad`.
|
||||
## `%e` - Static mark core
|
||||
|
||||
A scry with a `care` of `%e` will return a statically typed `nave:clay` `mark`
|
||||
core. The `path` in the scry specifies the `mark`. The type returned is a
|
||||
`(nave:clay [type] [diff])`, where `[type]` is the type the `mark` takes and
|
||||
`[diff]` is the type taken by the `mark` specified in `+form:grad`.
|
||||
|
||||
Example:
|
||||
|
||||
@ -63,9 +210,12 @@ Example:
|
||||
.^((nave:clay noun noun) %ce %/noun)
|
||||
```
|
||||
|
||||
## %f - Stat. mark convert.
|
||||
---
|
||||
|
||||
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`.
|
||||
## `%f` - Stat. mark convert
|
||||
|
||||
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`.
|
||||
|
||||
```
|
||||
> =a .^($-(text mime) %cf %/txt/mime)
|
||||
@ -73,11 +223,19 @@ A scry with a `care` of `%f` will return a static `mark` conversion gate. The `p
|
||||
[p=/text/plain q=[p=3 q=7.303.014]]
|
||||
```
|
||||
|
||||
## %p - File permissions.
|
||||
---
|
||||
|
||||
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.
|
||||
## `%p` - File permissions
|
||||
|
||||
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.
|
||||
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]`](/reference/arvo/clay/data-types#dictclay) where the head is read
|
||||
permissions and the tail is write permissions.
|
||||
|
||||
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.
|
||||
|
||||
Example:
|
||||
|
||||
@ -86,9 +244,13 @@ Example:
|
||||
[[src=/ rul=[mod=%white who=[p={} q={}]]] src=/ rul=[mod=%white who=[p={} q={}]]]
|
||||
```
|
||||
|
||||
## %r - File as vase.
|
||||
---
|
||||
|
||||
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.
|
||||
## `%r` - File as vase
|
||||
|
||||
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.
|
||||
|
||||
Examples:
|
||||
|
||||
@ -110,19 +272,28 @@ Examples:
|
||||
Crash!
|
||||
```
|
||||
|
||||
## %s - Misc. scries.
|
||||
---
|
||||
|
||||
A scry with a `care` of `%s` is for miscellaneous internal and debug functions and is liable to change in the future.
|
||||
## `%s` - Misc. scries
|
||||
|
||||
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.
|
||||
A scry with a `care` of `%s` is for miscellaneous internal and debug functions
|
||||
and is liable to change in the future.
|
||||
|
||||
### %yaki - Commit.
|
||||
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.
|
||||
|
||||
This will return the [yaki:clay](/reference/arvo/clay/data-types#yaki-clay-commit) of the specified commit. It takes a [tako:clay](/reference/arvo/clay/data-types#tako-clay-commit-reference).
|
||||
### `%yaki` - Commit
|
||||
|
||||
This will return the [yaki:clay](/reference/arvo/clay/data-types#yakiclay) of
|
||||
the specified commit. It takes a
|
||||
[tako:clay](/reference/arvo/clay/data-types#takoclay).
|
||||
|
||||
Example:
|
||||
|
||||
Here we scry the [dome:clay](/reference/arvo/clay/data-types#dome-desk-data) for `%`, get the latest `tako:clay` and the do a `%s` scry for the `yaki:clay` in question.
|
||||
Here we scry the [dome:clay](/reference/arvo/clay/data-types#domeclay) for `%`,
|
||||
get the latest `tako:clay` and the do a `%s` scry for the `yaki:clay` in
|
||||
question.
|
||||
|
||||
```
|
||||
> =/ =dome:clay .^(dome:clay %cv %)
|
||||
@ -141,36 +312,42 @@ Here we scry the [dome:clay](/reference/arvo/clay/data-types#dome-desk-data) for
|
||||
]
|
||||
```
|
||||
|
||||
### %blob - File blob.
|
||||
---
|
||||
|
||||
This will return the [blob:clay](/reference/arvo/clay/data-types#blob-clay-data) of some file. It takes a [lobe:clay](/reference/arvo/clay/data-types#lobe-clay-data-reference).
|
||||
### `%blob` - File blob
|
||||
|
||||
This will return the [page:clay](/reference/arvo/clay/data-types#pageclay) of
|
||||
some file. It takes a [lobe:clay](/reference/arvo/clay/data-types#lobeclay).
|
||||
|
||||
Example:
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
```
|
||||
> =/ =arch .^(arch %cy %/gen/hood/hi/hoon)
|
||||
?~ fil.arch
|
||||
~
|
||||
.^(blob:clay %cs %/blob/(scot %uv u.fil.arch))
|
||||
[ %direct
|
||||
p=0vp.k7nsm.qkdr3.t17rp.33bae.8gajg.v27gi.40itr.2u9qa.nppbt.7k255
|
||||
.^(page:clay %cs %/blob/(scot %uv u.fil.arch))
|
||||
[ p=%hoon
|
||||
q
|
||||
[ p=%hoon
|
||||
q
|
||||
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
|
||||
]
|
||||
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
|
||||
]
|
||||
```
|
||||
|
||||
### %hash - Commit hash.
|
||||
---
|
||||
|
||||
This will return the `@uvI` content hash of the specified commit. It takes a `tako:clay`.
|
||||
### `%hash` - Commit hash
|
||||
|
||||
This will return the `@uvI` (256-bit) content hash of the specified commit. It
|
||||
takes a [`tako:clay`](/reference/arvo/clay/data-types#takoclay).
|
||||
|
||||
Example:
|
||||
|
||||
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.
|
||||
Here we grab the [`dome:clay`](/reference/arvo/clay/data-types#domeclay) for `%`
|
||||
with a `%v` scry, get the latest
|
||||
[`tako:clay`](/reference/arvo/clay/data-types#takoclay) and then do a `%s`
|
||||
`%hash` scry for it.
|
||||
|
||||
```
|
||||
> =/ =dome:clay .^(dome:clay %cv %)
|
||||
@ -179,7 +356,9 @@ Here we grab the `dome:clay` for `%` with a `%v` scry, get the latest `tako:clay
|
||||
0v16.er7uq.oke4u.cru7u.nglu9.q3su7.6ub1o.bh4qk.r5uav.ut12d.5rdl5
|
||||
```
|
||||
|
||||
### %cage - File as cage.
|
||||
---
|
||||
|
||||
### `%cage` - File as cage
|
||||
|
||||
This will return a `cage` of the data of some file. It takes a `lobe:clay`.
|
||||
|
||||
@ -201,13 +380,25 @@ Here we grab the `lobe:clay` of `/gen/hood/hi/hoon` with a `%y` scry, then use i
|
||||
]
|
||||
```
|
||||
|
||||
### %open - Build prelude.
|
||||
---
|
||||
|
||||
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.
|
||||
### `%open` - Build prelude
|
||||
|
||||
### %late - Latest case.
|
||||
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.
|
||||
|
||||
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]`.
|
||||
---
|
||||
|
||||
### `%late` - Latest case
|
||||
|
||||
This will return the most recent revision number of a `desk` that has been fully
|
||||
downloaded. The type it returns is a
|
||||
[`cass:clay`](/reference/arvo/clay/data-types#cassclay). 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]`.
|
||||
|
||||
Example:
|
||||
|
||||
@ -221,9 +412,15 @@ cass=[ud=50 da=~2021.4.22..10.38.50..57a8]
|
||||
cass=[ud=0 da=~2000.1.1]
|
||||
```
|
||||
|
||||
### %base - Merge-base.
|
||||
---
|
||||
|
||||
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`.
|
||||
### `%base` - Merge-base
|
||||
|
||||
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`.
|
||||
|
||||
Examples:
|
||||
|
||||
@ -237,9 +434,15 @@ Examples:
|
||||
~
|
||||
```
|
||||
|
||||
## %t - List files.
|
||||
---
|
||||
|
||||
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`.
|
||||
## `%t` - List files
|
||||
|
||||
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`.
|
||||
|
||||
Examples:
|
||||
|
||||
@ -265,9 +468,13 @@ Examples:
|
||||
~
|
||||
```
|
||||
|
||||
## %u - Check exists.
|
||||
---
|
||||
|
||||
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.
|
||||
## `%u` - Check exists
|
||||
|
||||
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.
|
||||
|
||||
Examples:
|
||||
|
||||
@ -286,9 +493,12 @@ Examples:
|
||||
%.n
|
||||
```
|
||||
|
||||
## %v - Desk state.
|
||||
---
|
||||
|
||||
A scry with a care of `%v` will return the entire state of a `desk` as a `dome:clay`.
|
||||
## `%v` - Desk state
|
||||
|
||||
A scry with a care of `%v` will return the entire state of a `desk` as a
|
||||
[`dome:clay`](/reference/arvo/clay/data-types#domeclay).
|
||||
|
||||
Example:
|
||||
|
||||
@ -300,9 +510,14 @@ Example:
|
||||
|
||||
Note: If you try printing this it will take forever and probably OOM your ship.
|
||||
|
||||
## %w - Revision number.
|
||||
---
|
||||
|
||||
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.
|
||||
## `%w` - Revision number
|
||||
|
||||
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`](/reference/arvo/clay/data-types#cassclay) like `[ud=@ud da=@da]`
|
||||
where `ud` is the revision number and `da` is the date.
|
||||
|
||||
Example:
|
||||
|
||||
@ -311,9 +526,12 @@ Example:
|
||||
[ud=2 da=~2021.4.13..19.12.49..3389]
|
||||
```
|
||||
|
||||
## %x - Read file.
|
||||
---
|
||||
|
||||
A scry with a `care` of `%x` will return the raw data of a file as an `@` or crash if it's a directory.
|
||||
## `%x` - Read file
|
||||
|
||||
A scry with a `care` of `%x` will return the raw data of a file as an `@` or
|
||||
crash if it's a directory.
|
||||
|
||||
Examples:
|
||||
|
||||
@ -332,11 +550,16 @@ Examples:
|
||||
Crash!
|
||||
```
|
||||
|
||||
## %y - Read arch.
|
||||
---
|
||||
|
||||
## `%y` - Read arch
|
||||
|
||||
A scry with a `care` of `%y` will return the `arch` of a file or directory.
|
||||
|
||||
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.
|
||||
An `arch` is a `[fil=(unit lobe:clay) dir=(map @ta ~)]`. The `fil` will contain
|
||||
the [`lobe:clay`](/reference/arvo/clay/data-types#lobeclay) 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.
|
||||
|
||||
It will return the bunt of an `arch` if the file or directory is not found.
|
||||
|
||||
@ -373,9 +596,13 @@ Examples:
|
||||
[fil=~ dir={}]
|
||||
```
|
||||
|
||||
## %z - Content hash.
|
||||
---
|
||||
|
||||
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.
|
||||
## `%z` - Content hash
|
||||
|
||||
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.
|
||||
|
||||
The type returned is a `@uxI`.
|
||||
|
||||
@ -395,3 +622,5 @@ Examples:
|
||||
> .^(@uvI %cz %/foobar)
|
||||
0v0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@ -3,9 +3,17 @@ title = "API Reference"
|
||||
weight = 6
|
||||
+++
|
||||
|
||||
This document details all the `task`s you're likely to use to interact with Clay, as well as the `gift`s you'll receive in response. Each section has a corresponding practical example in the [Examples](/reference/arvo/clay/examples) document. Many of the types referenced are detailed in the [Data Types](/reference/arvo/clay/data-types) document. It may also be useful to look at the `++ clay` section of `/sys/lull.hoon` in Arvo where these `task`s, `gift`s and data structures are defined.
|
||||
This document details all the `task`s you're likely to use to interact with
|
||||
Clay, as well as the `gift`s you'll receive in response. Most sections have a
|
||||
corresponding practical example in the [Examples](/reference/arvo/clay/examples)
|
||||
document. Many of the types referenced are detailed in the [Data
|
||||
Types](/reference/arvo/clay/data-types) document. It may also be useful to look
|
||||
at the `++ clay` section of `/sys/lull.hoon` in Arvo where these `task`s,
|
||||
`gift`s and data structures are defined.
|
||||
|
||||
The 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.
|
||||
The 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.
|
||||
|
||||
## `%warp` - Read and track
|
||||
|
||||
@ -60,6 +68,8 @@ The [case](/reference/arvo/clay/data-types#case-specifying-a-commit) specifies t
|
||||
|
||||
[See here for an example of using %sing.](/reference/arvo/clay/examples#sing)
|
||||
|
||||
---
|
||||
|
||||
### `%next` - Await next
|
||||
|
||||
```hoon
|
||||
@ -74,6 +84,8 @@ If you subscribe to the current `case` of the `desk`, Clay will not respond unti
|
||||
|
||||
[See here for an example of using %next.](/reference/arvo/clay/examples#next)
|
||||
|
||||
---
|
||||
|
||||
### `%mult` - Next of any
|
||||
|
||||
```hoon
|
||||
@ -96,6 +108,8 @@ You can use a different `care` for each of the files specified by the `path` if
|
||||
|
||||
[See here for an example of using %mult.](/reference/arvo/clay/examples#mult)
|
||||
|
||||
---
|
||||
|
||||
### `%many` - Track range
|
||||
|
||||
```hoon
|
||||
@ -128,6 +142,8 @@ When you reach the end of the subscribed range of `case`s, Clay will send you a
|
||||
|
||||
[See here for an example of using %many.](/reference/arvo/clay/examples#many)
|
||||
|
||||
---
|
||||
|
||||
### Cancel Subscription
|
||||
|
||||
To 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.
|
||||
@ -136,6 +152,8 @@ To cancel a subscription, you just send a `%warp` with a null `(unit rave)` in t
|
||||
|
||||
[See here for an example of cancelling a subscription.](/reference/arvo/clay/examples#cancel-subscription)
|
||||
|
||||
---
|
||||
|
||||
## Write and Modify
|
||||
|
||||
### `%info` - Write
|
||||
@ -166,6 +184,200 @@ Here are examples of using each of these as well as making multiple changes in o
|
||||
- [%mut](/reference/arvo/clay/examples#mut)
|
||||
- [Multiple Changes](/reference/arvo/clay/examples#multiple-changes)
|
||||
|
||||
---
|
||||
|
||||
## Apps and updates
|
||||
|
||||
### `%rein` - Force apps
|
||||
|
||||
```hoon
|
||||
[%rein des=desk ren=rein]
|
||||
```
|
||||
|
||||
Force on/off apps on a desk. A
|
||||
[`rein:clay`](/reference/arvo/clay/data-types#rein) is a `map` from Gall agent
|
||||
name to `?`, where `%.y` is *on* and `%.n` is *off*. By default, a live desk
|
||||
will run the agents defined in its `desk.bill` manifest, so this is used to
|
||||
either stop agents in its manifest or start agents which aren't in its manifest.
|
||||
|
||||
Note that the given `rein` overrides the existing one set by a previous `%rein`
|
||||
task.
|
||||
|
||||
---
|
||||
|
||||
### `%tire` - App state sub
|
||||
|
||||
```hoon
|
||||
[%tire p=(unit ~)]
|
||||
```
|
||||
|
||||
A `%tire` task subscribes to, or unsubscribes from, updates to the state of
|
||||
apps. If `p` is non-null, it subscribes. If `p` is null, it unsubscribes.
|
||||
|
||||
Once subscribed, you'll immediately receive a `%tire` `gift`, which looks like:
|
||||
|
||||
```hoon
|
||||
[%tire p=(each rock:tire wave:tire)]
|
||||
```
|
||||
|
||||
You'll continue to receive `%tire` `gift`s each time app states change.
|
||||
|
||||
A `rock:tire` is a:
|
||||
|
||||
```hoon
|
||||
+$ rock (map desk [=zest wic=(set weft)])
|
||||
```
|
||||
|
||||
The [`zest:clay`](/reference/arvo/clay/data-types#zestclay) says whether the
|
||||
desk is running (`%live`), suspended (`%dead`), or suspended pending a
|
||||
kernel-compatible update (`%held`). The `wic` set contains the `weft`s (kernel
|
||||
versions) of any queued updates.
|
||||
|
||||
A `wave:tire` is a:
|
||||
|
||||
```hoon
|
||||
+$ wave ::
|
||||
$% [%wait =desk =weft] :: blocked
|
||||
[%warp =desk =weft] :: unblocked
|
||||
[%zest =desk =zest] :: running
|
||||
== ::
|
||||
```
|
||||
|
||||
It's an app state delta for a particular desk.
|
||||
|
||||
---
|
||||
|
||||
### `%wick` - Bump kernel
|
||||
|
||||
```hoon
|
||||
[%wick ~]
|
||||
```
|
||||
|
||||
Try to apply a queued kernel update.
|
||||
|
||||
---
|
||||
|
||||
### `%zest` - App state
|
||||
|
||||
```hoon
|
||||
[%zest des=desk liv=zest]
|
||||
```
|
||||
|
||||
A `%zest` `task` suspends or unsuspends a desk. the
|
||||
[`zest:clay`](/reference/arvo/clay/data-types#zestclay) in `liv` is one of:
|
||||
|
||||
- `%live`: running.
|
||||
- `%dead`: suspended.
|
||||
- `%held`: suspended pending kernel update.
|
||||
|
||||
---
|
||||
|
||||
## `%tomb` - Tombstoning
|
||||
|
||||
```hoon
|
||||
[%tomb =clue]
|
||||
```
|
||||
|
||||
Tombstoning is the deletion of data for old desk revisions. Clay has a single
|
||||
`%tomb` `task`, but its [`clue:clay`](/reference/arvo/clay/data-types#clueclay)
|
||||
has a number of different possible actions:
|
||||
|
||||
```hoon
|
||||
+$ clue :: murder weapon
|
||||
$% [%lobe =lobe] :: specific lobe
|
||||
[%all ~] :: all safe targets
|
||||
[%pick ~] :: collect garbage
|
||||
[%norm =ship =desk =norm] :: set default norm
|
||||
[%worn =ship =desk =tako =norm] :: set commit norm
|
||||
[%seek =ship =desk =cash] :: fetch source blobs
|
||||
== ::
|
||||
```
|
||||
|
||||
We'll look at each of these in turn.
|
||||
|
||||
### `%lobe` - Specific page
|
||||
|
||||
```hoon
|
||||
[%lobe =lobe]
|
||||
```
|
||||
|
||||
A `%tomb` `task` with a `%lobe` `clue` will tombstone the `page` matching the
|
||||
given [`lobe:clay`](/reference/arvo/clay/data-types#lobeclay). If the `page` in
|
||||
question is used in the current revision of any desks, it will fail. Otherwise,
|
||||
it will be tombstoned globally.
|
||||
|
||||
---
|
||||
|
||||
### `%all` - Everything
|
||||
|
||||
```hoon
|
||||
[%all ~]
|
||||
```
|
||||
|
||||
A `%tomb` `task` with an `%all` `clue` will tombstone everything that's not used
|
||||
by current desk revisions, globally. This should be used with caution.
|
||||
|
||||
---
|
||||
|
||||
### `%pick` - Collect garbage
|
||||
|
||||
```hoon
|
||||
[%pick ~]
|
||||
```
|
||||
|
||||
A `%tomb` `task` with a `%pick` `clue` will perform garbage collection,
|
||||
tombstoning any data that should be tombstoned according to current tombstoning
|
||||
policy ([`norm`](/reference/arvo/clay/data-types#normclay)s).
|
||||
|
||||
---
|
||||
|
||||
### `%norm` - Default policy
|
||||
|
||||
```hoon
|
||||
[%norm =ship =desk =norm]
|
||||
```
|
||||
|
||||
A `%tomb` `task` with a `%norm` `clue` will set the default tombstoning policy
|
||||
for the given `desk` and `ship`. A
|
||||
[`norm:clay`](/referende/arvo/clay/data-types#normclay) is an `(axal ?)`. An
|
||||
`axal` is like a recursive `arch`, and is defined in `arvo.hoon`. The `?` says
|
||||
whether to *keep* the given file or directory. You may want to look at the `+of`
|
||||
axal engine in `arvo.hoon` for constructing and manipulating the `norm`.
|
||||
|
||||
Note the given `norm` will overwrite the existing one for the the ship/desk in
|
||||
question. If you want to modify the existing one, you'll need to retrieve it and
|
||||
make your changes.
|
||||
|
||||
---
|
||||
|
||||
### `%worn` - Commit policy
|
||||
|
||||
```hoon
|
||||
[%worn =ship =desk =tako =norm]
|
||||
```
|
||||
|
||||
A `%tomb` `task` with a `%worn` `clue` is like
|
||||
[`%norm`](#norm---default-policy), except it only applies to a specific commit
|
||||
for a ship/desk. The [`tako:clay`](/reference/arvo/clay/data-types#takoclay)
|
||||
denotes the commit to apply the policy.
|
||||
|
||||
---
|
||||
|
||||
### `%seek` - Backfill
|
||||
|
||||
```hoon
|
||||
[%seek =ship =desk =cash]
|
||||
```
|
||||
|
||||
A `%tomb` `task` with a `%seek` `clue` will attempt to retrieve missing,
|
||||
tombstoned data and integrate it into Clay's object store. The
|
||||
[`cash:clay`](/reference/arvo/clay/data-types#cashclay) is a reference to a
|
||||
commit on the given ship/desk as either a
|
||||
[`tako:clay`](/reference/arvo/clay/data-types#takoclay) or a
|
||||
[`case:clay`](/reference/arvo/clay/data-types#caseclay).
|
||||
|
||||
---
|
||||
|
||||
## Manage Mounts
|
||||
|
||||
Here we'll look at managing Clay unix mounts programmatically.
|
||||
@ -199,6 +411,8 @@ The type it returns is a `%hill` `gift`, which looks like:
|
||||
|
||||
[See here for an example of using %boat.](/reference/arvo/clay/examples#boat)
|
||||
|
||||
---
|
||||
|
||||
### `%mont` - Mount
|
||||
|
||||
```hoon
|
||||
@ -223,6 +437,8 @@ Clay does not return a `gift` in response to a `%mont` `%task`.
|
||||
|
||||
[See here for an example of using %mont.](/reference/arvo/clay/examples#mont)
|
||||
|
||||
---
|
||||
|
||||
### `%ogre` - Unmount
|
||||
|
||||
```hoon
|
||||
@ -241,6 +457,8 @@ Clay does not return a `gift` in response to a `%ogre` `task`.
|
||||
|
||||
[See here for an example of using %ogre.](/reference/arvo/clay/examples#ogre)
|
||||
|
||||
---
|
||||
|
||||
### `%dirk` - Commit
|
||||
|
||||
```hoon
|
||||
@ -259,6 +477,8 @@ Clay does not return a `gift` in response to a `%dirk` `task`.
|
||||
|
||||
[See here for an example of using %dirk.](/reference/arvo/clay/examples#dirk)
|
||||
|
||||
---
|
||||
|
||||
## Merge Desks
|
||||
|
||||
### `%merg` - Merge
|
||||
@ -302,6 +522,8 @@ If the merge failed, `p` will have a head of `%.n` and then a `[term tang]` wher
|
||||
|
||||
[See here for an example of using %merg.](/reference/arvo/clay/examples#merg)
|
||||
|
||||
---
|
||||
|
||||
## Permissions
|
||||
|
||||
For 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.
|
||||
@ -386,6 +608,8 @@ Clay does not return a `gift` in response to a `%perm` `task`.
|
||||
|
||||
[See here for an example of using %perm.](/reference/arvo/clay/examples#perm)
|
||||
|
||||
---
|
||||
|
||||
### `%cred` - Add group
|
||||
|
||||
```hoon
|
||||
@ -408,6 +632,8 @@ Clay does not return a `gift` in response to a `%cred` `task`.
|
||||
|
||||
[See here for an example of using %cred.](/reference/arvo/clay/examples#cred)
|
||||
|
||||
---
|
||||
|
||||
### `%crew` - Get groups
|
||||
|
||||
```hoon
|
||||
@ -432,6 +658,8 @@ The `cez` is just a map from group name to `crew` which is just a `(set ship)`.
|
||||
|
||||
[See here for an example of using %crew.](/reference/arvo/clay/examples#crew)
|
||||
|
||||
---
|
||||
|
||||
### `%crow` - Group files
|
||||
|
||||
```hoon
|
||||
@ -460,6 +688,8 @@ The `gift` you get back is a `%croz` which looks like:
|
||||
|
||||
[See here for an example of using %crow.](/reference/arvo/clay/examples#crow)
|
||||
|
||||
---
|
||||
|
||||
## Foreign Ships
|
||||
|
||||
Here we'll looking at making Clay requests to a foreign ship.
|
||||
@ -485,6 +715,8 @@ The foreign ship will respond only if correct permissions have been set. See the
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
#### Example
|
||||
|
||||
[See here for examples of requests to foreign ships.](/reference/arvo/clay/examples#foreign-ships)
|
||||
@ -500,3 +732,5 @@ Note that all subfolders and individual files within the `desk` must permit your
|
||||
#### Example
|
||||
|
||||
[See here for examples of requests to foreign ships.](/reference/arvo/clay/examples#foreign-ships)
|
||||
|
||||
---
|
||||
|
||||
Loading…
Reference in New Issue
Block a user