urbit/developers.urbit.org
1
1
Fork 0
mirror of https://github.com/urbit/developers.urbit.org.git synced 2024-08-17 09:40:33 +03:00
Code Issues Packages Projects Releases Wiki Activity

clay: update types ref

Browse Source
This commit is contained in:
Tinnus Napbus 2023-08-09 23:43:42 +12:00
parent 4461ff3b8b
commit 9bac8a7b8e
3 changed files with 642 additions and 463 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

995
content/reference/arvo/clay/data-types.md
View File

File diff suppressed because it is too large Load Diff

52
content/reference/arvo/clay/scry.md
View File

@ -49,7 +49,7 @@ Example:
### `/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.
[`rang`](/reference/arvo/clay/data-types#rang) from Clay's state.
Example:
@ -90,7 +90,7 @@ The type returned is:
(set [@p rave:clay])
```
See the [`$rave:clay`](/reference/arvo/clay/data-types#raveclay) data
See the [`$rave:clay`](/reference/arvo/clay/data-types#rave) data
type entry for more details of the `$rave` structure.
Example:
@ -122,7 +122,7 @@ Example:
### `/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
[`cone`](/reference/arvo/clay/data-types#cone) containing the `dome`s
and associated metadata for all desks, foreign and local.
Example:
@ -149,7 +149,7 @@ Example:
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
[`zest`](/reference/arvo/clay/data-types#zest) specifies whether apps on the
desk are running or suspended. The `wic` set contains the `weft`s (kernel
versions) of any queued updates.
@ -198,7 +198,7 @@ Example:
## `%b` - Dyn. mark core
A scry with a `care` of `%b` will produce a `dais:clay` processed `mark` core
A scry with a `care` of `%b` will produce a `dais` processed `mark` core
for the specified `mark`. The `path` in the scry is a `mark`.
Example:
@ -209,7 +209,7 @@ Example:
## %c - Dyn. mark convert
A scry with a `care` of `%c` will produce a `tube:clay` dynamically typed `mark`
A scry with a `care` of `%c` will produce a `tube` dynamically typed `mark`
conversion gate. The `path` specifies two `mark`s - _from_ and _to_, like
`/txt/noun`.
@ -243,7 +243,7 @@ Example:
## `%e` - Static mark core
A scry with a `care` of `%e` will return a statically typed `nave:clay` `mark`
A scry with a `care` of `%e` will return a statically typed `nave` `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`.
@ -273,7 +273,7 @@ A scry with a `care` of `%f` will return a static `mark` conversion gate. The
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
dict:clay]`](/reference/arvo/clay/data-types#dict) 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
@ -329,14 +329,14 @@ you use. We'll look at each in turn.
### `%yaki` - Commit
This will return the [yaki:clay](/reference/arvo/clay/data-types#yakiclay) of
This will return the [yaki:clay](/reference/arvo/clay/data-types#yaki) of
the specified commit. It takes a
[tako:clay](/reference/arvo/clay/data-types#takoclay).
[tako:clay](/reference/arvo/clay/data-types#tako).
Example:
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
Here we scry the [dome:clay](/reference/arvo/clay/data-types#dome) for `%`,
get the latest `tako` and the do a `%s` scry for the `yaki` in
question.
```
@ -360,13 +360,13 @@ question.
### `%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).
This will return the [page:clay](/reference/arvo/clay/data-types#page) of
some file. It takes a [lobe:clay](/reference/arvo/clay/data-types#lobe).
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` of `/gen/hood/hi/hoon` with a `%y` scry, then use
it to do a `%s` scry for the `blob` of the file.
```
> =/ =arch .^(arch %cy %/gen/hood/hi/hoon)
@ -384,13 +384,13 @@ it to do a `%s` scry for the `blob:clay` of the file.
### `%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).
takes a [`tako`](/reference/arvo/clay/data-types#tako).
Example:
Here we grab the [`dome:clay`](/reference/arvo/clay/data-types#domeclay) for `%`
Here we grab the [`dome`](/reference/arvo/clay/data-types#dome) for `%`
with a `%v` scry, get the latest
[`tako:clay`](/reference/arvo/clay/data-types#takoclay) and then do a `%s`
[`tako`](/reference/arvo/clay/data-types#tako) and then do a `%s`
`%hash` scry for it.
```
@ -404,11 +404,11 @@ with a `%v` scry, get the latest
### `%cage` - File as cage
This will return a `cage` of the data of some file. It takes a `lobe:clay`.
This will return a `cage` of the data of some file. It takes a `lobe`.
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 `cage` of the data.
Here we grab the `lobe` of `/gen/hood/hi/hoon` with a `%y` scry, then use it to do a `%s` scry for the `cage` of the data.
```
> =/ =arch .^(arch %cy %/gen/hood/hi/hoon)
@ -438,10 +438,10 @@ 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`](/reference/arvo/clay/data-types#cassclay). The `case` in the
[`cass`](/reference/arvo/clay/data-types#cass). 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
specified `desk`, this will just return the bunt of a `cass` like
`cass=[ud=0 da=~2000.1.1]`.
Example:
@ -542,7 +542,7 @@ Examples:
## `%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).
[`dome`](/reference/arvo/clay/data-types#dome).
Example:
@ -560,7 +560,7 @@ Note: If you try printing this it will take forever and probably OOM your ship.
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]`
[`cass`](/reference/arvo/clay/data-types#cass) like `[ud=@ud da=@da]`
where `ud` is the revision number and `da` is the date.
Example:
@ -602,7 +602,7 @@ Crash!
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`](/reference/arvo/clay/data-types#lobeclay) hash if it's a file,
the [`lobe`](/reference/arvo/clay/data-types#lobe) 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.

58
content/reference/arvo/clay/tasks.md
View File

@ -24,8 +24,8 @@ Clay from a kernel development perspective.
A `%warp` `task` is for reading and subscribing to files and directories.
The `wer` field is the target ship. The `(unit rave)` of the
[riff](/reference/arvo/clay/data-types#riffclay) is null to cancel an existing
subscription, otherwise the [rave](/reference/arvo/clay/data-types#raveclay) is
[riff](/reference/arvo/clay/data-types#riff) is null to cancel an existing
subscription, otherwise the [rave](/reference/arvo/clay/data-types#rave) is
tagged with one of:
- `%sing` - Read a single file or directory.
@ -51,10 +51,10 @@ A `%wris` `gift` looks like:
[%writ p=riot] :: response
```
The `unit` of the [riot](/reference/arvo/clay/data-types#riotclay) will be null
The `unit` of the [riot](/reference/arvo/clay/data-types#riot) will be null
if the target file cannot be found or if a subscription has ended (depending on
context). Otherwise it will have a
[rant](/reference/arvo/clay/data-types#rantclay) with a `cage` containing the
[rant](/reference/arvo/clay/data-types#rant) with a `cage` containing the
data you requested. Its contents will vary depending on the kind of request and
`care`.
@ -68,13 +68,13 @@ Now we'll look at each of the `rave` request types in turn.
This `rave` is for reading a single file or directory immediately.
The `care` of the [mood](/reference/arvo/clay/data-types#moodclay) will
The `care` of the [mood](/reference/arvo/clay/data-types#mood) will
determine what you can read and what type of data will be returned. See the
[care](/reference/arvo/clay/data-types#careclay) documentation and
[care](/reference/arvo/clay/data-types#care) documentation and
[scry](/reference/arvo/clay/scry) documentation for details on the various
`care`s.
The [case](/reference/arvo/clay/data-types#caseclay) specifies the `desk`
The [case](/reference/arvo/clay/data-types#case) specifies the `desk`
revision and you can use whichever kind you prefer. The `path` will usually be
a path to a file or directory like `/gen/hood/hi/hoon` but may be something
else depending on the `care`.
@ -92,7 +92,7 @@ else depending on the `care`.
```
This subscribes to the next version of the specified file. See
[here](/reference/arvo/clay/data-types#moodclay) for details of the `mood`
[here](/reference/arvo/clay/data-types#mood) for details of the `mood`
structure.
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`.
@ -151,7 +151,7 @@ large and fairly complicated. The `nako` structure is defined in the
you're unlikely to work with it yourself.
The `from` and `to` fields of the
[moat](/reference/arvo/clay/data-types#moatclay) specify the range of `case`s
[moat](/reference/arvo/clay/data-types#moat) 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.
@ -189,18 +189,18 @@ To cancel a subscription, you just send a `%warp` with a null `(unit rave)` in t
To write or modify a file, we send Clay a `%info` `task`.
If the head of the [nori](/reference/arvo/clay/data-types#noriclay) `dit` is
If the head of the [nori](/reference/arvo/clay/data-types#nori) `dit` is
`%|`, it's a request to add a label to a commit, and the `nori` looks like `[%|
p=@tas q=(unit aeon)]` where `p` is the label and `q` is the
[`aeon`](/reference/arvo/clay/data-types#aeonclay) (commit reference). If `q`
[`aeon`](/reference/arvo/clay/data-types#aeon) (commit reference). If `q`
is null, the label is applied to the latest commit in the desk.
If the head of the `nori` is `%&`, it's a request to add, delete or modify one
or more files in the given desk, and looks like `[%& p=soba]`. The
[soba](/reference/arvo/clay/data-types#sobaclay) in the `nori` is just a list
[soba](/reference/arvo/clay/data-types#soba) in the `nori` is just a list
of changes so you can make more than one change in one request. Its `path` is
just the path to a file like `/gen/hood/hi/hoon` and the
[miso](/reference/arvo/clay/data-types#misoclay) is one of these types of
[miso](/reference/arvo/clay/data-types#miso) is one of these types of
requests:
- `%del` - Delete a file.
@ -232,7 +232,7 @@ Here are examples of using each of these as well as making multiple changes in o
```
Force on/off apps on a desk. A
[`rein:clay`](/reference/arvo/clay/data-types#reinclay) is a `map` from Gall agent
[`rein`](/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.
@ -265,7 +265,7 @@ A `rock:tire` is a:
+$ rock (map desk [=zest wic=(set weft)])
```
The [`zest:clay`](/reference/arvo/clay/data-types#zestclay) says whether the
The [`zest`](/reference/arvo/clay/data-types#zest) 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.
@ -301,7 +301,7 @@ Try to apply a queued kernel update.
```
A `%zest` `task` suspends or unsuspends a desk. the
[`zest:clay`](/reference/arvo/clay/data-types#zestclay) in `liv` is one of:
[`zest`](/reference/arvo/clay/data-types#zest) in `liv` is one of:
- `%live`: running.
- `%dead`: suspended.
@ -316,7 +316,7 @@ A `%zest` `task` suspends or unsuspends a desk. the
```
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)
`%tomb` `task`, but its [`clue`](/reference/arvo/clay/data-types#clue)
has a number of different possible actions:
```hoon
@ -339,7 +339,7 @@ We'll look at each of these in turn.
```
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
given [`lobe`](/reference/arvo/clay/data-types#lobe). If the `page` in
question is used in the current revision of any desks, it will fail. Otherwise,
it will be tombstoned globally.
@ -364,7 +364,7 @@ by current desk revisions, globally. This should be used with caution.
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).
policy ([`norm`](/reference/arvo/clay/data-types#norm)s).
---
@ -376,7 +376,7 @@ policy ([`norm`](/reference/arvo/clay/data-types#normclay)s).
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
[`norm`](/referende/arvo/clay/data-types#norm) 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`.
@ -395,7 +395,7 @@ make your changes.
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)
for a ship/desk. The [`tako`](/reference/arvo/clay/data-types#tako)
denotes the commit to apply the policy.
---
@ -408,10 +408,10 @@ denotes the commit to apply the policy.
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
[`cash`](/reference/arvo/clay/data-types#cash) 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).
[`tako`](/reference/arvo/clay/data-types#tako) or a
[`case`](/reference/arvo/clay/data-types#case).
---
@ -458,7 +458,7 @@ The type it returns is a `%hill` `gift`, which looks like:
A `%mont` `task` mounts the specified `beam` to the specified `term` mount point.
A `beam:clay` is the following structure:
A `beam` is the following structure:
```hoon
+$ beam [[p=ship q=desk r=case] s=path] :: global name
@ -484,7 +484,7 @@ Clay does not return a `gift` in response to a `%mont` `%task`.
A `%ogre` `task` unmounts the specified mount.
It's defined in `lull.hoon` as taking `$@(desk beam)` but in fact it will only unmount the target when specified as a `term` mount name. Passing it a `desk` will incidentally work if the mount is named the same as the `desk` but otherwise it won't work. Passing it a `beam:clay` will simply not work.
It's defined in `lull.hoon` as taking `$@(desk beam)` but in fact it will only unmount the target when specified as a `term` mount name. Passing it a `desk` will incidentally work if the mount is named the same as the `desk` but otherwise it won't work. Passing it a `beam` will simply not work.
#### Returns
@ -569,9 +569,9 @@ If permissions are not set for a particular file, they will be inherited from th
A group is called a `crew` and is just a `set` of ships with a `@ta` name.
The permissions for each file or directory are a pair of `dict:clay` where the head is read permissions and the tail is write permissions.
The permissions for each file or directory are a pair of `dict` where the head is read permissions and the tail is write permissions.
A `dict:clay` is this structure:
A `dict` is this structure:
```hoon
+$ dict [src=path rul=real] :: effective permission
@ -740,7 +740,7 @@ To read files on a foreign `desk`, you just send Clay a `%warp` `task` (as you w
Clay only allows a subset of `care`s to be used remotely. They are:
- `%u` - Check for existence of file.
- `%v` - Get entire `dome:clay` state of a desk.
- `%v` - Get entire `dome` state of a desk.
- `%w` - Get revision number.
- `%x` - Get data of file.
- `%y` - Get `arch` of file or directory.