mirror of
https://github.com/urbit/developers.urbit.org.git
synced 2024-08-17 09:40:33 +03:00
clay: update types ref
This commit is contained in:
parent
4461ff3b8b
commit
9bac8a7b8e
File diff suppressed because it is too large
Load Diff
@ -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.
|
||||
|
||||
|
@ -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.
|
||||
|
Loading…
Reference in New Issue
Block a user