@@ -0,0 +1,368 @@
1++++
2+title = "Dill"
3+weight = 3
4+template = "doc.html"
5++++
6+
7+# Dill
8+
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.
11+
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.
17+
18+## Dill Tasks
19+
20+
21+### `%belt`
22+
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.
25+
26+#### Accepts
27+
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`.
30+
31+```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
38+ {$hey ~} :: refresh
39+ {$met p/@} :: meta-key
40+ {$ret ~} :: return
41+ {$rez p/@ud q/@ud} :: resize, cols, rows
42+ {$txt p/(list @c)} :: utf32 text
43+ {$yow p/gill:gall} :: connect to app
44+ == ::
45+```
46+
47+#### Returns
48+
49+Dill returns no `gift` in response to a `%belt` `task`.
50+
51+
52+### `%blew`
53+
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.
56+
57+#### Accepts
58+
59+```hoon
60+[p=@ud q=@ud]
61+```
62+
63+`p` is the number of columns and `q` is the number of rows.
64+
65+#### Returns
66+
67+Dill returns no `gift` in response to a `%blew` `task`.
68+
69+
70+### `%boot`
71+
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).
77+
78+#### Accepts
79+
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.
83+
84+#### Returns
85+
86+`%boot` does not return a `gift`.
87+
88+
89+
90+### `%crud`
91+
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`.
95+
96+#### Accepts
97+
98+```hoon
99+[err=@tas tac=(list tank)]
100+```
101+
102+`err` is the type of error and `tac` is the associated error message.
103+
104+#### Returns
105+
106+`%crud` does not return a `gift`.
107+
108+
109+### `%flog`
110+
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`.
113+
114+#### Accepts
115+
116+`%flog` `task`s can take any valid Dill `task` as an argument.
117+
118+#### Returns
119+
120+`%flog` never returns a `gift` on its own, but the wrapped `task` might.
121+
122+#### Example
123+
124+`%crud` `task`s from other vanes are typically passed to Dill wrapped in a
125+`%flog` `task` to print errors to the terminal.
126+
127+
128+
129+### `%flow`
130+
131+This `task` is not used.
132+
133+
134+### `%hail`
135+
136+`%hail` refreshes the terminal by sending an empty message to the default duct
137+for Dill,
138+causing the terminal to redraw itself (?)
139+
140+#### Accepts
141+
142+```hoon
143+[ ~ ]
144+```
145+
146+#### Returns
147+
148+`%hail` returns no `gift`s.
149+
150+
151+### `%heft`
152+
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.
155+
156+#### Accepts
157+
158+```hoon
159+[ ~ ]
160+```
161+
162+#### Returns
163+
164+`%heft` does not directly return any `gift`s, but each `%wegh` `task` sent will
165+return a `%mass` `gift`.
166+
167+
168+### `%hook`
169+
170+This task is not used.
171+
172+
173+### `%harm`
174+
175+This `task` is not used.
176+
177+
178+### `%init`
179+
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.
183+
184+Note that this is not actually the first `task` passed to Dill - see [%boot](#%boot).
185+
186+#### Accepts
187+
188+`%init` takes no arguments.
189+
190+#### Returns
191+
192+`%init` returns no `gift`s.
193+
194+
195+### `%knob`
196+
197+`%knob` sets the verbosity level for each error tag.
198+
199+#### Accepts
200+
201+```hoon
202+[tag=@tas level=log-level]
203+```
204+
205+`tag` is the error tag. `level` is the verbosity, set to either `%hush`,
206+`%soft`, or `%loud`.
207+
208+#### Returns
209+
210+`%knob` does not return a gift.
211+
212+
213+
214+
215+### `%noop`
216+
217+`%noop` does nothing - it stands for "no operation".
218+
219+#### Accepts
220+
221+```hoon
222+[ ~ ]
223+```
224+
225+#### Returns
226+
227+This `task`, predictably, returns nothing.
228+
229+#### Example
230+
231+This can be useful if a shell command requires a Dill `task` but you don't want
232+Dill to do anything.
233+
234+
235+
236+### `%talk`
237+
238+This `task` is not used.
239+
240+### `%text`
241+
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.
245+
246+#### Accepts
247+
248+```hoon
249+[p=tape]
250+```
251+
252+#### Returns
253+
254+This `task` returns zero or more `%blit` `gift`s, each containing a .
255+
256+
257+### `%trim`
258+
259+`%trim` is a common vane `task` used to reduce memory usage. However, it does
260+nothing for Dill.
261+
262+#### Accepts
263+
264+```hoon
265+[p=@ud]
266+```
267+
268+This is a common parameter for `%trim` `task`s across all vanes but does nothing
269+for Dill.
270+
271+#### Returns
272+
273+This `task` returns no `gift`s.
274+
275+
276+
277+### `%vega`
278+
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.
281+
282+#### Accepts
283+
284+```hoon
285+[ ~ ]
286+```
287+
288+#### Returns
289+
290+This `task` returns no `gift`s.
291+
292+
293+
294+## Arvo tasks
295+
296+These `task`s live in `task:able:dill` but are passed directly to the Arvo
297+kernel for processing.
298+
299+### `%lyra`
300+
301+This `task` updates the kernel.
302+
303+#### Accepts
304+
305+```hoon
306+[p=@t q=@t]
307+```
308+
309+`p` is the contents of the new `hoon.hoon` and `q` is the contents of the new `arvo.hoon`.
310+
311+#### Returns
312+
313+This `task` returns no `gift`s.
314+
315+
316+### `%pack`
317+
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`.
321+
322+#### Accepts
323+
324+```hoon
325+[ ~ ]
326+```
327+
328+#### Returns
329+
330+This `task` returns no `gift`s.
331+
332+
333+### `%veer`
334+
335+This `task` is used to install `zuse` and vanes. It is handled by `+veer` in
336+`arvo.hoon`.
337+
338+#### Accepts
339+
340+```hoon
341+[p=@ta q=path r=@t]
342+```
343+
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
347+the case of `zuse`.
348+
349+#### Returns
350+
351+This `task` returns no `gift`s.
352+
353+
354+### `%verb`
355+
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).
359+
360+#### Accepts
361+
362+```hoon
363+[ ~ ]
364+```
365+
366+#### Returns
367+
368+This `task` returns no `gift`s.