@@ -0,0 +1,368 @@
9+In this document we describe the public interface for Dill. Namely, we describe
10+each `task` that Dill can be `pass`ed, and which `gift`(s) Dill can `give` in return.
12+Dill is unique among vanes since it is technically the first vane to be booted (though we
13+regard Jael as the "true" first vane). As a result, there are four `task`s in
14+`task:able:dill` for which Dill acts only as a middleman that passes the `task`s
15+directly to the Arvo kernel. Thus we have split this document into a [Dill
16+tasks](#dill-tasks) section and an [Arvo tasks](#arvo-tasks) section.
23+Every keystroke entered into the console triggers a `%belt` `task` for Dill which contains information about the keystroke, such as which key was pressed
24+and from which terminal.
28+`%belt` `task`s come in a number of different types, corresponding to different
29+keystrokes. You can find this list in `+dill-belt` in `zuse.hoon`.
32+++ dill-belt :: new belt
33+ $% {$aro p/?($d $l $r $u)} :: arrow key
34+ {$bac ~} :: true backspace
35+ {$cru p/@tas q/(list tank)} :: echo error
36+ {$ctl p/@} :: control-key
37+ {$del ~} :: true delete
39+ {$met p/@} :: meta-key
41+ {$rez p/@ud q/@ud} :: resize, cols, rows
42+ {$txt p/(list @c)} :: utf32 text
43+ {$yow p/gill:gall} :: connect to app
49+Dill returns no `gift` in response to a `%belt` `task`.
54+This `task` is called whenever the terminal emulator is resized, so that Dill can adjust
55+the text output to fit the new window size.
63+`p` is the number of columns and `q` is the number of rows.
67+Dill returns no `gift` in response to a `%blew` `task`.
72+This `task` is used only once, when Arvo first enters the [adult
73+stage](@/docs/tutorials/arvo/arvo.md#structural-interface-core). Dill is
74+technically the first vane to be activated, via the `%boot` `task`, which then
75+send Jael (considered the the "true" first vane) an `%init` `task`, which then goes on to
76+call `%init` `task`s for other vanes (including Dill).
80+`%boot` takes an argument that is either `%dawn` or `%fake`. `%dawn` is the one
81+used in any typical scenario and activates the ordinary vane initialization
82+process outlined above, while `%fake` is a debugging tool.
86+`%boot` does not return a `gift`.
92+This `task` is used by Dill to produce error reports. It prints the received
93+error message(s) (a `(list tank)`) to the terminal. The level of detail of the
94+error message is set by `$log-level`, which is either `%hush`, `%soft`, or `%loud`.
99+[err=@tas tac=(list tank)]
102+`err` is the type of error and `tac` is the associated error message.
106+`%crud` does not return a `gift`.
111+A `%flog` `task` is a wrapper over a `task` sent by another vane. Dill removes the wrapper
112+and sends the bare `task` to itself over the default `duct`.
116+`%flog` `task`s can take any valid Dill `task` as an argument.
120+`%flog` never returns a `gift` on its own, but the wrapped `task` might.
124+`%crud` `task`s from other vanes are typically passed to Dill wrapped in a
125+`%flog` `task` to print errors to the terminal.
131+This `task` is not used.
136+`%hail` refreshes the terminal by sending an empty message to the default duct
138+causing the terminal to redraw itself (?)
148+`%hail` returns no `gift`s.
153+`%heft` causes Dill to `pass` a `%wegh` `task` to all other vanes (but not to
154+itself), thus obtaining a complete digest of Arvo's memory usage.
164+`%heft` does not directly return any `gift`s, but each `%wegh` `task` sent will
165+return a `%mass` `gift`.
170+This task is not used.
175+This `task` is not used.
180+This `task` is called only once, when Arvo first enters the [adult
181+stage](@/docs/tutorials/arvo/arvo.md#structural-interface-core). It performs
182+initial setup for Dill, such as setting the width of the console.
184+Note that this is not actually the first `task` passed to Dill - see [%boot](#%boot).
188+`%init` takes no arguments.
192+`%init` returns no `gift`s.
197+`%knob` sets the verbosity level for each error tag.
202+[tag=@tas level=log-level]
205+`tag` is the error tag. `level` is the verbosity, set to either `%hush`,
210+`%knob` does not return a gift.
217+`%noop` does nothing - it stands for "no operation".
227+This `task`, predictably, returns nothing.
231+This can be useful if a shell command requires a Dill `task` but you don't want
238+This `task` is not used.
242+This `task` prints a `tape` to the dojo by first converting it from a UTF8
243+`tape` to a `list` of UTF32 codepoints (`@c`'s) and then recursively popping off a character from the
244+`tape` and sending it to to Unix to be printed into the terminal via a `%blit` event.
254+This `task` returns zero or more `%blit` `gift`s, each containing a .
259+`%trim` is a common vane `task` used to reduce memory usage. However, it does
268+This is a common parameter for `%trim` `task`s across all vanes but does nothing
273+This `task` returns no `gift`s.
279+This is a common vane `task` used to inform the vane that the kernel has been
280+upgraded. Dill does not do anything in response to this.
290+This `task` returns no `gift`s.
296+These `task`s live in `task:able:dill` but are passed directly to the Arvo
297+kernel for processing.
301+This `task` updates the kernel.
309+`p` is the contents of the new `hoon.hoon` and `q` is the contents of the new `arvo.hoon`.
313+This `task` returns no `gift`s.
318+This `task` defragments and deduplicates Arvo's memory. This is ultimately
319+performed by the interpreter so you won't find the code in `arvo.hoon` but
320+rather under `c3__pack` in `urbit/worker/main.c`.
330+This `task` returns no `gift`s.
335+This `task` is used to install `zuse` and vanes. It is handled by `+veer` in
344+`p` is the vane letter, `q` is the formal `path` to the
345+vane, and `r` is the source code for the vane. The vane letter is `%` followed
346+by the first letter of the vane in lowercase, such as `%d` for Dill. `p=%$` in
351+This `task` returns no `gift`s.
356+This `task` toggles verbose mode for all of Arvo, which is located here since
357+Dill is the vane that prints errors. To be precise, `%verb` toggles the laconic
358+bit `lac` in the [Arvo state](@/docs/tutorials/arvo/arvo.md#the-state).
368+This `task` returns no `gift`s.