mirror of
https://github.com/urbit/developers.urbit.org.git
synced 2024-08-16 17:20:35 +03:00
dill: bring all reference docs up-to-date
- update scries - update and restructure tasks - update data types - update overview in lieu of dill now supporting multiple sessions
This commit is contained in:
parent
544db1eee2
commit
334a07fb3c
@ -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.
|
||||
|
||||
---
|
||||
|
@ -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.
|
||||
|
@ -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
|
||||
```
|
||||
|
||||
---
|
||||
|
@ -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`.
|
||||
|
||||
---
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user