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

dill: bring all reference docs up-to-date

Browse Source 
- update scries
- update and restructure tasks
- update data types
- update overview in lieu of dill now supporting multiple sessions
This commit is contained in:
Tinnus Napbus 2023-06-29 00:40:39 +12:00
parent 544db1eee2
commit 334a07fb3c
4 changed files with 625 additions and 379 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

313
content/reference/arvo/dill/data-types.md
View File

@ -7,180 +7,253 @@ Here are the data types used by Dill, as defined in `/sys/lull.hoon`.
## `$blew`
Terminal dimension.
```hoon
+$ blew [p=@ud q=@ud]
+$ blew [p=@ud q=@ud]
```
Terminal dimension; `p` is columns, `q` is rows. This structure is passed to Dill by the runtime in a [%blew](/reference/arvo/dill/tasks#blew) `task` whenever the dimensions of the terminal changes.
`p` is columns, `q` is rows. This structure is passed to Dill by the
runtime in a [%blew](/reference/arvo/dill/tasks#blew) `task` whenever
the dimensions of the terminal changes.
---
## `$belt`
```hoon
+$ belt
$? bolt
$% [%mod mod=?(%ctl %met %hyp) key=bolt]
[%txt p=(list @c)]
[%ctl p=@c]
[%met p=@c]
== ==
```
Terminal client input.
A `$belt` is passed to Dill in a [%belt](/reference/arvo/dill/tasks#belt) `task` by the runtime whenever there is input, such as a user typing in the console. This is only used between the terminal client and Dill, a [$dill-belt](#dill-belt) is used between Dill and Arvo.
```hoon
+$ belt :: client input
$? bolt :: simple input
[%mod mod=?(%ctl %met %hyp) key=bolt] :: w/ modifier
[%txt p=(list @c)] :: utf32 text
::TODO consider moving %hey, %rez, %yow here ::
== ::
```
A `$belt` is passed to Dill in a
[%belt](/reference/arvo/dill/tasks#belt) `task` by the runtime whenever
there is input, such as a user typing in the console. This is only used
between the terminal client and Dill, a [$dill-belt](#dill-belt) is used
between Dill and Arvo.
May either be a [$bolt](#bolt) or one of:
- `%mod` - Modifier (Ctrl, Meta or Hyper) plus [key].
- `%txt` - A series of characters
- `%ctl` - Ctrl+[key], deprecated in favour of `%mod`.
- `%met` - Meta+[key], deprecated in favour of `%mod`.
- `%mod` - Modifier (Ctrl, Meta or Hyper) plus a key (see
[`$bolt`](#bolt).
- `%txt` - A series of UTF-32 characters.
--
## `$bolt`
```hoon
+$ bolt
$@ @c
$% [%aro p=?(%d %l %r %u)]
[%bac ~]
[%del ~]
[%hit r=@ud c=@ud]
[%ret ~]
==
```
Simple input.
Either a single simple character or one of:
```hoon
+$ bolt :: simple input
$@ @c :: simple keystroke
$% [%aro p=?(%d %l %r %u)] :: arrow key
[%bac ~] :: true backspace
[%del ~] :: true delete
[%hit x=@ud y=@ud] :: mouse click
[%ret ~] :: return
== ::
```
Either a single UTF-32 character or one of:
- `%aro` - Arrow keys.
- `%bac` - Backspace key.
- `%del` - Delete key.
- `%hit` - Mouse click - `r` is row and `c` is column. Note these are zero-indexed, with `[0 0]` being the _bottom left_ corner.
- `%hit` - Mouse click - `r` is row and `c` is column. Note these are
zero-indexed, with `[0 0]` being the _bottom left_ corner.
- `%ret` - Return (Enter) key.
---
## `$blit`
```hoon
+$ blit
$% [%bel ~]
[%clr ~]
[%hop p=@ud]
[%klr p=stub]
[%lin p=(list @c)]
[%mor ~]
[%sag p=path q=*]
[%sav p=path q=@]
[%url p=@t]
==
```
Terminal client output.
A `$blit` is given to the terminal client by Dill in a `%blit` `gift` when it wants to print some text, clear the screen, go _ding_ or what have you.
```hoon
+$ blit :: client output
$% [%bel ~] :: make a noise
[%clr ~] :: clear the screen
[%hop p=$@(@ud [x=@ud y=@ud])] :: set cursor col/pos
[%klr p=stub] :: put styled
[%mor p=(list blit)] :: multiple blits
[%nel ~] :: newline
[%put p=(list @c)] :: put text at cursor
[%sag p=path q=*] :: save to jamfile
[%sav p=path q=@] :: save to file
[%url p=@t] :: activate url
[%wyp ~] :: wipe cursor line
== ::
```
This is only used between Dill and the terminal client, a [$dill-blit](#dill-blit) is used instead between Arvo and Dill.
A `$blit` is given to the terminal client by Dill in a `%blit` `gift`
when it wants to print some text, clear the screen, go _ding_ or what
have you.
This is directly used between Dill and the terminal client, while a
[$dill-blit](#dill-blit) is used between Arvo and Dill. A `$dill-blit`
includes the `$blit` union as a subset.
A `$blit` is one of:
- `%bel` - Ring the terminal bell.
- `%clr` - Clear the screen.
- `%hop` - Set cursor position, `p` specifies its position on the prompt line.
- `%hop` - Set cursor position. If `p` is an atom, it specifies the
horizontal position on the prompt line. If `p` is a cell, it
represents a 2D location where `x` is columns and `y` is
rows.
- `%klr` - Set styled line, the `$stub` specifies the text and style.
- `%lin` - Set current line, `p` contains the text.
- `%mor` - Newline.
- `%sag` - Save to jamfile, typically in `/[pier]/.urb/put/`. `p` is `/[path]/[filename]/[extension]`. For example, `/foo/bar` will save it in `/[pier]/.urb/put/foo.bar`, `/a/b/c/foo/bar` will save it in `/[pier]/.urb/put/a/b/c/foo.bar`, and `/foo` will save it in `/[pier]/.urb/put.foo`. `q` is the `noun` to `jam` and save in the file.
- `%sav` - Save to file. Same behaviour as `%sag` except `q` is an `atom` rather than a `noun` and therefore doesn't need to be `jam`med. The `atom` is written to disk as if it were the bytestring in the tail of an `$octs`. That is, `%sav`ing the `cord` `'abcdef'`, whose `@ux` value is `0x6665.6463.6261`, results in a unix file whose hex dump renders as `61 62 63 64 65 66`.
- `%mor` - multiple `$blit`s.
- `%nel` - a newline.
- `%put` - put text (as a list of UTF-32 characters) at the current
cursor position.
- `%sag` - Save to jamfile, typically in `/[pier]/.urb/put/`. `p` is
`/[path]/[filename]/[extension]`. For example, `/foo/bar` will save it
in `/[pier]/.urb/put/foo.bar`, `/a/b/c/foo/bar` will save it in
`/[pier]/.urb/put/a/b/c/foo.bar`, and `/foo` will save it in
`/[pier]/.urb/put.foo`. `q` is the `noun` to `jam` and save in the
file.
- `%sav` - Save to file. Same behaviour as `%sag` except `q` is an
`atom` rather than a `noun` and therefore doesn't need to be `jam`med.
The `atom` is written to disk as if it were the bytestring in the tail
of an `$octs`. That is, `%sav`ing the `cord` `'abcdef'`, whose `@ux`
value is `0x6665.6463.6261`, results in a unix file whose hex dump
renders as `61 62 63 64 65 66`.
- `%url` - Activate URL, `p` is the URL.
- `%wyp` - clear the cursor line.
---
## `$dill-belt`
```hoon
+$ dill-belt
$% [%aro p=?(%d %l %r %u)]
[%bac ~]
[%cru p=@tas q=(list tank)]
[%ctl p=@]
[%del ~]
[%hey ~]
[%met p=@]
[%ret ~]
[%rez p=@ud q=@ud]
[%txt p=(list @c)]
[%yow p=gill:gall]
==
```
Terminal input for Arvo.
While [$belt](#belt) is used between the terminal client and Dill, `$dill-belt` is used between Dill and Arvo.
```hoon
+$ dill-belt :: arvo input
$% belt :: client input
[%cru p=@tas q=(list tank)] :: errmsg (deprecated)
[%hey ~] :: refresh
[%rez p=@ud q=@ud] :: resize, cols, rows
[%yow p=gill:gall] :: connect to app
== ::
```
a `$dill-belt` is one of:
A [$belt](#belt) is used between the terminal client and Dill, while a
`$dill-belt` is used between Dill and Arvo. A `$dill-belt` includes the
`$belt` union as a subset.
- `%aro` - Arrow keys.
- `%bac` - Backspace key.
- `%cru` - Echo error, `p` is an error `@tas` and `q` is a traceback.
- `%ctl` - Ctrl+[key].
- `%del` - Delete key.
a `$dill-belt` is either [`$belt`](#belt) or one of:
- `%cru` - Echo error, `p` is some error tag and `q` is a stack trace.
- `%hey` - Refresh.
- `%met` - Meta+[key].
- `%ret` - Return key (Enter).
- `%rez` - Terminal resized, `p` is columns and `q` is rows.
- `%txt` - Text input.
- `%yow` - Connect to app.
---
## `$dill-blit`
```hoon
+$ dill-blit
$% [%bel ~]
[%clr ~]
[%hop p=@ud]
[%klr p=stub]
[%mor p=(list dill-blit)]
[%pom p=stub]
[%pro p=(list @c)]
[%qit ~]
[%out p=(list @c)]
[%sag p=path q=*]
[%sav p=path q=@]
[%url p=@t]
==
```
Terminal output from Arvo.
While [$blit](#blit) is used between Dill and the terminal client, `$dill-blit` is used between Arvo and Dill.
```hoon
+$ dill-blit :: arvo output
$% blit :: client output
[%qit ~] :: close console
== ::
```
A `$dill-blit` is one of:
While [$blit](#blit) is used between Dill and the terminal client,
`$dill-blit` is used between Arvo and Dill. A `$blit` is a subset of a
`$dill-blit`.
A `$dill-blit` is either a [`$blit`](#blit) or a:
- `%bel` - Terminal bell.
- `%clr` - Clear screen.
- `%hop` - Set cursor position, `p` is its horizontal position on the prompt line.
- `%klr` - Styled text, the `$stub` specifies both the text and style.
- `%mor` - Multiple `$dill-blit`.
- `%pom` - Styled prompt, the `$stub` specifies both the text and style.
- `%pro` - Set prompt, `p` is the text for the prompt.
- `%qit` - Close console.
- `%out` - Print text.
- `%sag` - Save `noun` to jamfile. See [$blit](#blit) section for further details.
- `%sav` - Save `atom` to file. See [$blit](#blit) section for further details.
- `%url` - Activate URL.
---
## `$flog`
```hoon
+$ flog
$% [%crop p=@ud]
[%crud p=@tas q=(list tank)]
[%heft ~]
[%meld ~]
[%pack ~]
[%text p=tape]
[%verb ~]
==
```
Wrapped Dill `task`s.
These are a subset of Dill's `task`s which can be wrapped in a `%flog` `task`. See the [API Reference](/reference/arvo/dill/tasks) document for details of each of these `task`s.
```hoon
+$ flog :: sent to %dill
$% [%crop p=@ud] :: trim kernel state
$>(%crud told) ::
[%heft ~] ::
[%meld ~] :: unify memory
[%pack ~] :: compact memory
$>(%text told) ::
[%verb ~] :: verbose mode
== ::
```
These are a subset of Dill's `task`s which can be wrapped in a `%flog`
`task`. See the [API Reference](/reference/arvo/dill/tasks) document for
details of each of these `task`s.
---
## `$poke`
Dill to userspace.
```hoon
+$ poke :: dill to userspace
$: ses=@tas :: target session
dill-belt :: input
== ::
```
A [`$dill-belt`](#dill-belt) (client input) for a particular session.
---
## `$session-task`
A subset of [Dill's `task`s](/reference/arvo/dill/tasks#session-tasks)
for interacting with a particular session.
```hoon
+$ session-task :: session request
$% [%belt p=belt] :: terminal input
[%blew p=blew] :: terminal config
[%flee ~] :: unwatch session
[%hail ~] :: terminal refresh
[%open p=dude:gall q=(list gill:gall)] :: setup session
[%shut ~] :: close session
[%view ~] :: watch session blits
== ::
```
This type is used in the [`%shot`](/reference/arvo/dill/tasks#shot)
wrapper `task`.
See the [Session Tasks](/reference/arvo/dill/tasks#session-tasks) entry
in the API reference for more details of these `task`s.
---
## `$told`
A subset of [Dill's `task`s](/reference/arvo/dill/tasks#session-tasks)
for basic text printing.
```hoon
+$ told :: system output
$% [%crud p=@tas q=tang] :: error
[%talk p=(list tank)] :: tanks (in order)
[%text p=tape] :: tape
== ::
```
See the [Told Tasks](/reference/arvo/dill/tasks#told-tasks) entry
in the API reference for more details of these `task`s.
---

61
content/reference/arvo/dill/dill.md
View File

@ -5,35 +5,72 @@ weight = 1
The terminal driver vane.
Keyboard events and the like from Unix are received by Dill as [%belt](/reference/arvo/dill/tasks#belt) `task`s, and Dill sends `%blit` `gift`s containing [$blit](/reference/arvo/dill/data-types#blit)s back to the runtime to be displayed in the Unix terminal. The manner of interacting with Dill differs depending on whether you're in userspace or kernelspace, as we'll explore below.
Keyboard events and the like from Unix are received by Dill as
[%belt](/reference/arvo/dill/tasks#belt) `task`s, and Dill sends `%blit`
`gift`s containing [$blit](/reference/arvo/dill/data-types#blit)s back to the
runtime to be displayed in the Unix terminal. The manner of interacting with
Dill differs depending on whether you're in userspace or kernelspace, as we'll
explore below.
## Kernelspace
For technical reasons, Dill performs a handful of system tasks related to booting a ship and some memory operations. Aside from those, other Vanes mostly just pass Dill [tasks](/reference/arvo/dill/tasks) to print error messages and the like to the terminal.
For technical reasons, Dill performs a handful of system tasks related to
booting a ship and some memory operations. Aside from those, other Vanes mostly
just pass Dill [tasks](/reference/arvo/dill/tasks) to print error messages and
the like to the terminal.
## Userspace
Unlike in kernelspace, userspace applications are unlikely to `%pass` Dill `task`s directly. Instead, Dill looks at things in terms of sessions. A session is a pipeline between a client and a handler, where:
Unlike in kernelspace, userspace applications are unlikely to `%pass` Dill
`task`s directly. Instead, Dill looks at things in terms of sessions. A session
is a pipeline between a client and a handler, where:
- The client is an external input source and output sink; a terminal with with dimensions and so forth.
- The handler is an application in Urbit that interprets input, maybe does something with it, maybe produces output to be displayed in the client, etc.
- The client is an external input source and output sink; a terminal with
dimensions and so forth.
- The handler is an application in Urbit that interprets input, maybe does
something with it, maybe produces output to be displayed in the client,
etc. The handler may itself handle and multiplex terminal interfaces for
other applications, as is the case with the `%hood` module `%drum`, or it
may be a stand-alone application.
There are plans for Dill to support multiple independent sessions (i.e. independent terminal clients displaying and processing different information at the same time), but at this stage Dill only supports a single session. The client for this default session is just the Unix terminal via the Urbit runtime. The handler for the default session is the `%hood` app, whose `drum` module does the heavy lifting.
Currently, Dill supports multiple *sessions*, but Vere (the runtime) only
supports a single Unix terminal *client* for the default session (`%$`). This
means any non-default sessions will need to be linked through the default
session handler `%drum` (a module of the `%hood` app) if they are to work in
the Unix terminal. Alternatively, a client could be built that talks to Dill
via the HTTP server Eyre in a similar way to the `%webterm` app, and
interacts with sessions entirely separately from the Unix terminal and its
`%drum` handler.
`drum` is the CLI app manager. By default you'll have a couple of CLI applications running—`%dojo` and `%chat-cli`—which you can switch between with `ctrl+x`. You may also have additional CLI apps which you have attached with the `|link` command. It's `drum` that keeps track of which one is active, which one input should be routed to, which one should be displayed, what each prompt should look like, and so forth. Dill itself is oblivious to the distinction between these CLI apps. It only sees the default session with `drum`, so it just passes all input to `drum` and display whatever `drum` gives it.
`%drum` is Arvo's CLI app manager. By default you'll have one CLI application
running: the `%dojo`. You may also have additional CLI apps which you have
started or attached with the `|link` command. It's `%drum` that keeps track of
which one is active, which one input should be routed to, which one should be
displayed, what each prompt should look like, and so forth. Dill itself is
oblivious to the distinction between these CLI apps. It only sees the session
with `%drum`, so it just passes all input to `%drum` and display whatever
`%drum` gives it.
While `drum` talks with Dill in `$dill-belt`s and `$dill-blit`s, it talks to CLI apps with `$sole-action`s and `$sole-event`s, which are defined in the `sole` library. For more information on the `sole` library and the related `shoe` library, and for information on how to build CLI apps, you can refer to the [CLI app tutorial](/guides/additional/cli-tutorial).
While `%drum` talks with Dill in `$dill-belt`s and `$dill-blit`s, it talks to
CLI apps with `$sole-action`s and `$sole-event`s, which are defined in the
`sole` library. For more information on the `sole` library and the related
`shoe` library, and for information on how to build CLI apps, you can refer to
the [CLI app tutorial](/guides/additional/cli-tutorial).
To give a basic idea of how keyboard events flow through these systems and produce terminal output, here's a diagram showing the messages in pseudo-Hoon:
To give a basic idea of how keyboard events flow through these systems and
produce terminal output, here's a diagram showing the messages in pseudo-Hoon:
![Dill userspace diagram](https://media.urbit.org/docs/arvo/dill/dill-userspace.svg)
You can use a [move trace](/reference/arvo/tutorials/move-trace) to get a hands-on feel for this data flow.
You can use a [move trace](/reference/arvo/tutorials/move-trace) to get a
hands-on feel for this data flow.
## Sections
[API Reference](/reference/arvo/dill/tasks) - The `task`s Dill takes and the `gift`s it returns.
[API Reference](/reference/arvo/dill/tasks) - The `task`s Dill takes and the
`gift`s it returns.
[Scry Reference](/reference/arvo/dill/scry) - The scry endpoints of Dill.
[Data Types](/reference/arvo/dill/data-types) - Reference documentation of the data types used by Dill.
[Data Types](/reference/arvo/dill/data-types) - Reference documentation of the
data types used by Dill.

45
content/reference/arvo/dill/scry.md
View File

@ -3,42 +3,39 @@ title = "Scry Reference"
weight = 3
+++
Here are the scry endpoints of Dill. They take a `%x` `care` and require the `desk` in the path prefix be empty, so the general format is `.^([type] %dx /=//=/[some-path])`.
Here are the scry endpoints of Dill. They require the `desk` in the path prefix
be empty, so the general format is `.^([type] %d[care] /=//=/[some-path])`.
Dill only has a couple of scry endpoints, both of which begin with `/session//`. The empty `//` would be where the target session would be specified, but at this stage Dill can only return a result for the default session, so it's always empty.
## `%x` - `/sessions`
## /sessions//line
Get all sessions.
A scry with a `care` of `%x` and a `path` of `/sessions//line` returns the current text of the prompt line of the default session. The type returned is a [$blit](/reference/arvo/dill/data-types#blit).
A scy with a `care` of `%x` and a `path` of `/sessions` returns a `(set @tas)`
of the current sessions. The `%$` session is the default session.
#### Example
```
> .^(blit:dill %dx /=//=/sessions//line)
[ %lin
p
~[
~-~~
~-z
~-o
~-d
~-~3a.
~-d
~-o
~-j
~-o
...truncated for brevity...
]
]
> .^((set @tas) %dy /=//=/sessions)
{%$}
```
## /sessions//cursor
---
A scry with a `care` of `%x` and a `path` of `/sessions//cursor` returns the current horizontal position of the cursor in the default session. The type returned is a `@ud`.
## `%u` - `/sessions/[ses]`
Does session exist?
A scry with a `care` of `%x` and a `path` of `/sessions/[ses]` where `[ses]` is
a session name returns a `?` of whether `[ses]` exists.
#### Example
```
> .^(@ud %dx /=//=/sessions//cursor)
44
> .^(? %du /=//=/sessions/$)
%.y
> .^(? %du /=//=/sessions/foo)
%.n
```
---

585
content/reference/arvo/dill/tasks.md
View File

@ -3,339 +3,478 @@ title = "API Reference"
weight = 2
+++
In this document we describe the public interface for Dill. Namely, we describe each `task` that Dill can be `pass`ed, and which `gift`(s) Dill can `give` in return.
In this document we describe the public interface for Dill. Namely, we
describe each `task` that Dill can be `pass`ed, and which `gift`(s) Dill
can `give` in return.
## `%belt`
Dill's `task`s are organized into three categories: [Session
`task`s](#session-tasks) for interacting with a particular session,
[Told `task`s](#told-tasks) for basic terminal printing, and
[system/miscellaneous `task`s](#system-misc-tasks) which are a combination of
general system `task`s and Dill `task`s which don't fit in the previous
two categories.
```hoon
[%belt p=belt]
```
## System & Misc. Tasks
Terminal input.
These are the Dill `task`s not otherwise categorized as [session
tasks](#session-tasks) or [told tasks](#told-tasks). Most of them are
interfaces for Vere or Arvo and do thing like toggle verbose mode,
defragment state, etc. The most notable Dill-specific `task` is
[`%shot`](#shot), which is used as a wrapper for the [session
tasks](#session-tasks) to specify the session. The [`%logs`](#logs)
`task` is also useful, letting you subscribe to all system output.
The runtime sends a `%belt` `task` to Dill whenever there is input in the terminal, such as a keystroke.
The [$belt](/reference/arvo/dill/data-types#belt) in `p` contains the input such as which key was pressed.
Dill will convert the `$belt` into a [$dill-belt](/reference/arvo/dill/data-types#dill-belt) and `%poke` the session handler (typically `drum`) with it.
This `task` would not typically be used from userspace.
#### Returns
Dill returns no `gift` in response to a `%belt` `task`.
## `%blew`
```hoon
[%blew p=blew]
```
Terminal resized.
The runtime passes Dill a `%blew` `task` whenever the terminal is resized.
The [$blew](/reference/arvo/dill/data-types#blew) specifies the new dimensions.
Dill will convert the `$blew` into a `%rez` [$dill-belt](/reference/arvo/dill/data-types#dill-belt) and `%poke`s the session handler (typically `drum`) with it.
This `task` would not typically be used from userspace.
#### Returns
Dill returns no `gift` in response to a `%blew` `task`.
## `%boot`
### `%boot`
```hoon
[%boot lit=? p=*]
```
This `task` is used only once, when Arvo first enters the [adult stage](/reference/arvo/overview#structural-interface-core). Dill is technically the first vane to be activated, via the `%boot` `task`, which then sends Jael (considered the "true" first vane) the `%dawn` or `%fake` `task` wrapped in the `%boot` `task`. Jael then goes on to call `%init` `task`s for other vanes (including Dill).
This `task` is used only once, when Arvo first enters the [adult
stage](/reference/arvo/overview#structural-interface-core). Dill is
technically the first vane to be activated, via the `%boot` `task`,
which then sends Jael (considered the "true" first vane) the `%dawn` or
`%fake` `task` wrapped in the `%boot` `task`. Jael then goes on to call
`%init` `task`s for other vanes (including Dill).
`lit` specifies whether to boot in lite mode. `p` is either a [%dawn](/reference/arvo/jael/data-types#dawn) or [%fake](/reference/arvo/jael/tasks#fake) `task:jael`. `%dawn` is for an ordinary boot and `%fake` is for booting a fake ship.
`lit` specifies whether to boot in lite mode. `p` is either a
[%dawn](/reference/arvo/jael/tasks#dawn) or
[%fake](/reference/arvo/jael/tasks#fake) `task:jael`. `%dawn` is for an
ordinary boot and `%fake` is for booting a fake ship.
This `task` would not be used from userspace.
#### Returns
Dill returns no `gift` in response to a `%boot` `task`, but it will `%pass` the wrapped `%dawn` or `%fake` `task` to Jael.
Dill returns no `gift` in response to a `%boot` `task`, but it will
`%pass` the wrapped `%dawn` or `%fake` `task` to Jael.
## `%crop`
---
### `%crop`
Trim kernel state.
```hoon
[%crop p=@ud]
```
Trim kernel state.
This `task` is the same as the [%trim](#trim) `task`. Like `%trim`, Dill does nothing with it.
This `task` is the same as the `%trim` vane `task`. Like `%trim`, Dill
does nothing with it.
#### Returns
Dill returns no `gift` in response to a `%crop` `task`.
## `%crud`
---
```hoon
[%crud p=@tas q=(list tank)]
```
Print error.
Dill prints the given error to the terminal. The verbosity for the particular `@tas` error tag specified in `p` is determined by the `level` set by a [%knob](#knob) `task` - either `%hush`, `%soft` or `%loud`. The default is `%loud`, where it will print the full `(list tank)` specified in `q`. See [%knob](#knob) for details of verbosity levels.
#### Returns
Dill does not return a `gift` in response to a `%crud` `task`.
## `%flee`
```hoon
[%flee session=~]
```
Unwatch a session to which you've previously subscribed with [%view](#view).
The ability to specify a session is not yet implemented in Dill, so `session` is always `~`, the default session.
#### Returns
Dill does not return a `gift` in response to a `%flee` `task`.
## `%flog`
### `%flog`
```hoon
[%flog p=flog]
```
A `%flog` `task` is a wrapper over a `task` sent by another vane. Dill removes the wrapper and sends the bare `task` to itself over the default `duct`.
A `%flog` `task` is a wrapper over a `task` sent by another vane. Dill
removes the wrapper and sends the bare `task` to itself over the default
`duct`.
A `%flog` `task` takes a [$flog](/reference/arvo/dill/data-types#flog) as its argument. A `$flog` is a subset of Dill's `task`s.
A `%flog` `task` takes a [$flog](/reference/arvo/dill/data-types#flog)
as its argument. A `$flog` is a subset of Dill's `task`s.
#### Returns
Dill does not return a `gift` in response to a `%flog` `task`.
## `%flow`
---
```hoon
[%flow p=@tas q=(list gill:gall)]
```
### `%heft`
Terminal config.
This `task` is not used.
## `%hail`
```hoon
[%hail ~]
```
Refresh.
Dill converts a `%hail` `task` into a `%hey` [$dill-belt](/reference/arvo/dill/data-types#dill-belt) and `%poke`s the session handler (typically `drum`) with it to handle the refresh.
This `task` would not be used from userspace.
#### Returns
Dill returns no `gift` in response to a `%hail` `task`.
## `%heft`
Produce memory report.
```hoon
[%heft ~]
```
Produce memory report.
When Dill receives a `%heft` `task` it passes Arvo a `%whey` `waif` to obtain a memory report and prints it to the terminal.
When Dill receives a `%heft` `task` it passes Arvo a `%whey` `waif` to
obtain a memory report and prints it to the terminal.
#### Returns
Dill does not return a `gift` in response to a `%heft` `task`.
## `%hook`
---
### `%logs`
Watch system output.
```hoon
[%hook ~]
[%logs p=(unit ~)]
```
This terminal hung up.
This task is not used.
## `%harm`
```hoon
[%harm ~]
```
All terminals hung up.
This `task` is not used.
## `%init`
```hoon
[%init ~]
```
This `task` is called only once, when Arvo first enters the [adult stage](/reference/arvo/overview#structural-interface-core). It performs initial setup for Dill, such as setting the width of the console.
Note that this is not actually the first `task` passed to Dill - see [%boot](#%boot).
This `task` would not be used from userspace.
A non-null `p` subscribes to system output, and a null `p` unsubscribes.
While subscribed, you'll receive each piece of output in a `%logs` gift
as it occurs.
#### Returns
Dill does not return a `gift` in response to a `%init` `task`.
Dill does not immediately return anything, but will give you a `%logs`
gifts each time system output occurs. A `%logs` gift looks like:
## `%meld`
```hoon
[%logs =told]
```
```
[%meld ~]
```
A `$told` is either a [`%crud`](#crud), [`%talk`](#talk) or
[`%text`](#text) task. See the
[`$told`](/reference/arvo/dill/data-types#dill-belt) entry in the data
types reference for more details.
---
### `%meld`
Deduplicate persistent state.
```hoon
[%meld ~]
```
Dill asks the runtime to perform the memory deduplication.
#### Returns
Dill does not return a `gift` in response to a `%meld` `task`.
## `%noop`
---
```hoon
[%noop ~]
```
### `%pack`
No operation.
A `%noop` `task` does nothing, as the name implies.
#### Returns
Dill does not return a `gift` in response to a `%noop` `task`.
## `%pack`
Defragment persistent state.
```hoon
[%pack ~]
```
Defragment persistent state.
Dill asks the runtime to perform the defragmentation.
#### Returns
Dill does not return a `gift` in response to a `%meld` `task`.
## `%talk`
---
### `%seat`
Install desk.
```hoon
[%talk p=tank]
[%seat =desk]
```
This `task` is not used.
## `%text`
```hoon
[%text p=tape]
```
Print `tape` to terminal.
Upon receiving a `%text` `task`, Dill will convert the `tape` given in `p` to a `(list @c)` and give it to the runtime in a `%blit` `gift` including a `%lin` [$blit](/reference/arvo/dill/data-types#blit).
This indirectly pokes `%hood` with a `%kiln-install` `mark` to install
the specified `desk`. You should just poke `%hood` directly rather than
using this.
#### Returns
Dill does not return a `gift` in response to a `%text` `task`, but it does give a `%blit` `gift` to the runtime which looks like:
Dill does not return a `gift` in response to a `%seat` `task`.
---
### `%shot`
Task for session.
```hoon
[%blit p=(list blit)]
[%shot ses=@tas task=session-task]
```
## `%view`
A `$session-task` is one of these `task`s: [`%belt`](#belt),
[`%blew`](#blew), [`%flee`](#flee), [`%hail`](#hail), [`%open`](#open),
[`%shut`](#shut), [`%view`](#view). See the
[`$session-task`](/reference/arvo/dill/data-types#session-task) entry in
the data types reference.
```hoon
[%view session=~]
```
---
Watch session.
### `%verb`
A `%view` `task` subscribes for a copy of all `%blit` `gift`s which Dill `%give`s for the default session. This `task` is used by the `%herm` app so it can convert the `$blit`s to JSON and render them in the web terminal.
The ability to specify a session is not yet implemented in Dill, so `session` is always `~`, the default session.
#### Returns
Dill will `%give` a copy of all `%blit`s for the default session. A `%blit` `gift` is:
```hoon
[%blit p=(list blit)]
```
## `%trim`
```hoon
[%trim p=@ud]
```
`%trim` is a common vane `task` used to reduce memory usage. It does nothing for Dill because Dill only keeps a minimal necessary state.
#### Returns
Dill does not return a `gift` in response to a `%trim` `task`.
## `%vega`
```hoon
[%vega ~]
```
This is a common vane `task` used to inform the vane that the kernel has been
upgraded. Dill does not do anything in response to this.
This `task` would not be used from userspace.
#### Returns
Dill returns no `gift` in response to a `%vega` `task`.
## `%verb`
Toggle Arvo verbose mode.
```hoon
[%verb ~]
```
This `task` toggles verbose mode for all of Arvo, which is located here since
Dill is the vane that prints errors. To be precise, `%verb` toggles the laconic
bit `lac` in the [Arvo state](/reference/arvo/overview#the-state) by passing a `%verb` `waif` to Arvo.
This `task` toggles verbose mode for all of Arvo, which is located here
since Dill is the vane that prints errors. To be precise, `%verb`
toggles the laconic bit `lac` in the [Arvo
state](/reference/arvo/overview#the-state) by passing a `%verb` `waif`
to Arvo.
#### Returns
Dill does not return a `gift` in response to a `%verb` `task`.
## `%knob`
---
## Session Tasks
These `task`s are for interacting with a particular session. These all
would normally be wrapped in a [`%shot`](#shot) `task` to specify the
session, rather than sent directly.
This subset of Dill's `task`s are defined in the [`$session-task`
type](/reference/arvo/dill/data-types#session-task).
### `%belt`
Terminal input.
```hoon
[%knob tag=term level=?(%hush %soft %loud)]
[%belt p=belt]
```
`%knob` sets the verbosity level for each error tag. The error `tag` can be any `@tas`. The given `tag` and `level` will be added to Dill's `veb` which maps tags to levels. Subsequent [%crud](#crud) `task`s will then print with the specified verbosity.
The [$belt](/reference/arvo/dill/data-types#belt) in `p` contains the
input such as which key was pressed. Dill will convert the `$belt` into
a [$dill-belt](/reference/arvo/dill/data-types#dill-belt) and `%poke` it
into the session handler agent for the session in question.
The `level`s behave like so:
- `%hush` - Completely silent, print nothing.
- `%soft` - Just print `crud: %error-tag event failed`, ignore any `tang` given in the `%crud`.
- `%loud` - Print the `%soft` message as well as the full `tang` given in the `%crud` `task`.
This `task` should be wrapped in a [`%shot`](#shot) `task` to specify
the session. Without the `%shot` wrapper, it will use the default
session (`%$`).
#### Returns
Dill does not return a `gift` in response to a `%knob` `task`.
Dill returns no `gift` in response to a `%belt` `task`.
---
### `%blew`
Terminal resized.
```hoon
[%blew p=blew]
```
The [$blew](/reference/arvo/dill/data-types#blew) specifies the new
dimensions.
Dill will convert the `$blew` into a `%rez`
[$dill-belt](/reference/arvo/dill/data-types#dill-belt) and `%poke`s the
session handler (typically `drum`) with it.
This `task` would not typically be used from userspace. Instead, it
would come in from the runtime for the default session (`%$`) when the
actual terminal were resized. If in an odd scenario it were used from
userspace, it would need to be wrapped in a [`%shot`](#shot) `task` to
specify a session other than `%$`.
#### Returns
Dill returns no `gift` in response to a `%blew` `task`.
---
### `%flee`
Unwatch a session to which you've previously subscribed with
[%view](#view).
```hoon
[%flee ~]
```
This `task` must be wrapped in a [`%shot`](#shot) `task` in order to
specify the session. Without that, it will default to the default
session (`%$`). The subscription to end will be determined implicitly by
the `duct`.
#### Returns
Dill does not return a `gift` in response to a `%flee` `task`.
---
### `%hail`
Refresh.
```hoon
[%hail ~]
```
Dill converts a `%hail` `task` into a `%hey`
[$dill-belt](/reference/arvo/dill/data-types#dill-belt) and `%poke`s the
session handler (typically `%drum`) with it.
This `task` would not typically be used from userspace. If in an odd
scenario it were used from userspace, it would need to be wrapped in a
[`%shot`](#shot) `task` to specify a session other than `%$`.
#### Returns
Dill returns no `gift` in response to a `%hail` `task`.
---
### `%open`
Setup session.
```hoon
[%open p=dude:gall q=(list gill:gall)]
```
This `task` is always wrapped in a [`%shot`](#shot) `task`, and creates
the new session specified in that wrapper. If it's not wrapped in a
`%shot` task, it will default to the default session (`%$`) and fail
because it already exists. This `task` is designed to be used by a
userspace session handler like `%drum` that multiplexes terminal
interfaces for multiple userspace applications, but could also be used
by a stand-alone application that talks to Dill directly.
The Gall agent specified in `p` is the session handler or stand-alone
application. The `q` field contains a list of `gill:gall`, which are
pairs of `[ship term]`, representing an app on a ship. The `gill`s in
`q` are the list of apps being managed by the session handler `q` that
should be notified of being connected to this session. If `p` were a
stand-alone application, `q` could be empty, or else just contain that
one app.
Dill will poke every agent listed in `q` (local or remote) with a
[`%yow` `$dill-belt`](/reference/arvo/dill/data-types#dill-belt), to let
it know it's been connected. It will also `%watch` the agent `p` for
[`$dill-blit`](/reference/arvo/dill/data-types#dill-blit)s in `%fact`s
with a `%dill-blit` `mark` on the `path` `/dill/[ses]` where `ses` is
the session specified in the [`%shot`](#shot) wrapper.
Additionally, the source of the `%open` request (as determined by the
`duct`, typically the agent in `p`) will begin receiving terminal output
gifts for the session in question. Essentially, it behaves as though you
also passed it a [`%view`](#view) task.
#### Returns
Dill does not give a `gift` in direct response to an `%open` `task`. It
will, however, start giving terminal output `%blit` `gift`s to the
requester as the occur for the session. A `%blit` `gift` looks like:
```hoon
[%blit p=(list blit)]
```
See the [`$blit`](/reference/arvo/dill/data-types#blit) entry in the
data type reference for details of what it can contain.
This subscription for `$blit`s can be stopped with a [`%flee`](#flee)
`task` at any time.
---
### `%shut`
Close session.
```hoon
[%shut ~]
```
This `task` needs to be wrapped in [`%shot`](#shot) `task` to specify
the session to close. Otherwise, it will default to the default session
(`%$`).
The session handler will be passed a `%leave`. Subscribers for `$blit`s
will not be notified, they'll just stop receiving `$blit`s.
#### Returns
Dill does not give a `gift` in response to a `%shut` `task`. It will,
however, pass a `%leave` to the session handler agent.
---
### `%view`
Watch session.
```hoon
[%view ~]
```
A `%view` `task` subscribes for a copy of all `%blit` `gift`s which Dill
`%give`s for the session in question. This `task` must be wrapped in a
[`%shot`](#shot) `task` which specifies the session if you want to
subscribe to anything other than the default session (`%$`).
#### Returns
Dill will begin giving a copy of all `%blit`s for the session specified
in the [`%shot`](#shot) wrapper, or the default session (`%$`) if a
`%shot` wrapper is not used. A `%blit` `gift` is:
```hoon
[%blit p=(list blit)]
```
See the [`$blit`](/reference/arvo/dill/data-types#blit) entry in the
data type reference for more details.
The subscription can be ended with a [`%flee`](#flee) `task`.
---
## Told Tasks
This subset of Dill `task`s are for printing things. They are defined in
the [`$told` type](/reference/arvo/dill/data-types#told).
### `%crud`
Print error.
```hoon
[%crud p=@tas q=tang]
```
Dill prints the given error to the terminal.
#### Returns
Dill does not return a `gift` in response to a `%crud` `task`.
---
### `%talk`
Print `tang` to terminal.
```hoon
[%talk p=(list tank)]
```
The `tank`s in `p` will be printed to the terminal, first to last.
#### Returns
Dill does not return a `gift` in response to a `%talk` `task`.
---
### `%text`
Print `tape` to terminal.
```hoon
[%text p=tape]
```
The `tape` in `p` will be printed to the terminal.
#### Returns
Dill does not return a `gift` in response to a `%text` `task`.
---