@@ -1,366 +0,0 @@
1−+++
2−title = "API Reference"
3−weight = 10
4−template = "doc.html"
5−+++
6−
7−In this document we describe the public interface for Dill. Namely, we describe
8−each `task` that Dill can be `pass`ed, and which `gift`(s) Dill can `give` in return.
9−
10−Dill is unique among vanes since it is technically the first vane to be booted (though we
11−regard Jael as the "true" first vane). As a result, there are four `task`s in
12−`task:able:dill` for which Dill acts only as a middleman that passes the `task`s
13−directly to the Arvo kernel. Thus we have split this document into a [Dill
14−tasks](#dill-tasks) section and an [Arvo tasks](#arvo-tasks) section.
15−
16−## Dill Tasks
17−
18−
19−### `%belt`
20−
21−Every keystroke entered into the console triggers a `%belt` `task` for Dill which contains information about the keystroke, such as which key was pressed
22−and from which terminal.
23−
24−#### Accepts
25−
26−`%belt` `task`s come in a number of different types, corresponding to different
27−keystrokes. You can find this list in `+dill-belt` in `zuse.hoon`.
28−
29−```hoon
30−++ dill-belt :: new belt
31− $% {$aro p/?($d $l $r $u)} :: arrow key
32− {$bac ~} :: true backspace
33− {$cru p/@tas q/(list tank)} :: echo error
34− {$ctl p/@} :: control-key
35− {$del ~} :: true delete
36− {$hey ~} :: refresh
37− {$met p/@} :: meta-key
38− {$ret ~} :: return
39− {$rez p/@ud q/@ud} :: resize, cols, rows
40− {$txt p/(list @c)} :: utf32 text
41− {$yow p/gill:gall} :: connect to app
42− == ::
43−```
44−
45−#### Returns
46−
47−Dill returns no `gift` in response to a `%belt` `task`.
48−
49−
50−### `%blew`
51−
52−This `task` is called whenever the terminal emulator is resized, so that Dill can adjust
53−the text output to fit the new window size.
54−
55−#### Accepts
56−
57−```hoon
58−[p=@ud q=@ud]
59−```
60−
61−`p` is the number of columns and `q` is the number of rows.
62−
63−#### Returns
64−
65−Dill returns no `gift` in response to a `%blew` `task`.
66−
67−
68−### `%boot`
69−
70−This `task` is used only once, when Arvo first enters the [adult
71−stage](/docs/arvo/overview#structural-interface-core). Dill is
72−technically the first vane to be activated, via the `%boot` `task`, which then
73−send Jael (considered the the "true" first vane) an `%init` `task`, which then goes on to
74−call `%init` `task`s for other vanes (including Dill).
75−
76−#### Accepts
77−
78−`%boot` takes an argument that is either `%dawn` or `%fake`. `%dawn` is the one
79−used in any typical scenario and activates the ordinary vane initialization
80−process outlined above, while `%fake` is a debugging tool.
81−
82−#### Returns
83−
84−`%boot` does not return a `gift`.
85−
86−
87−
88−### `%crud`
89−
90−This `task` is used by Dill to produce error reports. It prints the received
91−error message(s) (a `(list tank)`) to the terminal. The level of detail of the
92−error message is set by `$log-level`, which is either `%hush`, `%soft`, or `%loud`.
93−
94−#### Accepts
95−
96−```hoon
97−[err=@tas tac=(list tank)]
98−```
99−
100−`err` is the type of error and `tac` is the associated error message.
101−
102−#### Returns
103−
104−`%crud` does not return a `gift`.
105−
106−
107−### `%flog`
108−
109−A `%flog` `task` is a wrapper over a `task` sent by another vane. Dill removes the wrapper
110−and sends the bare `task` to itself over the default `duct`.
111−
112−#### Accepts
113−
114−`%flog` `task`s can take any valid Dill `task` as an argument.
115−
116−#### Returns
117−
118−`%flog` never returns a `gift` on its own, but the wrapped `task` might.
119−
120−#### Example
121−
122−`%crud` `task`s from other vanes are typically passed to Dill wrapped in a
123−`%flog` `task` to print errors to the terminal.
124−
125−
126−
127−### `%flow`
128−
129−This `task` is not used.
130−
131−
132−### `%hail`
133−
134−`%hail` refreshes the terminal by sending an empty message to the default duct
135−for Dill,
136−causing the terminal to redraw itself (?)
137−
138−#### Accepts
139−
140−```hoon
141−[ ~ ]
142−```
143−
144−#### Returns
145−
146−`%hail` returns no `gift`s.
147−
148−
149−### `%heft`
150−
151−`%heft` causes Dill to `pass` a `%wegh` `task` to all other vanes (but not to
152−itself), thus obtaining a complete digest of Arvo's memory usage.
153−
154−#### Accepts
155−
156−```hoon
157−[ ~ ]
158−```
159−
160−#### Returns
161−
162−`%heft` does not directly return any `gift`s, but each `%wegh` `task` sent will
163−return a `%mass` `gift`.
164−
165−
166−### `%hook`
167−
168−This task is not used.
169−
170−
171−### `%harm`
172−
173−This `task` is not used.
174−
175−
176−### `%init`
177−
178−This `task` is called only once, when Arvo first enters the [adult
179−stage](/docs/arvo/overview#structural-interface-core). It performs
180−initial setup for Dill, such as setting the width of the console.
181−
182−Note that this is not actually the first `task` passed to Dill - see [%boot](#%boot).
183−
184−#### Accepts
185−
186−`%init` takes no arguments.
187−
188−#### Returns
189−
190−`%init` returns no `gift`s.
191−
192−
193−### `%knob`
194−
195−`%knob` sets the verbosity level for each error tag.
196−
197−#### Accepts
198−
199−```hoon
200−[tag=@tas level=log-level]
201−```
202−
203−`tag` is the error tag. `level` is the verbosity, set to either `%hush`,
204−`%soft`, or `%loud`.
205−
206−#### Returns
207−
208−`%knob` does not return a gift.
209−
210−
211−
212−
213−### `%noop`
214−
215−`%noop` does nothing - it stands for "no operation".
216−
217−#### Accepts
218−
219−```hoon
220−[ ~ ]
221−```
222−
223−#### Returns
224−
225−This `task`, predictably, returns nothing.
226−
227−#### Example
228−
229−This can be useful if a shell command requires a Dill `task` but you don't want
230−Dill to do anything.
231−
232−
233−
234−### `%talk`
235−
236−This `task` is not used.
237−
238−### `%text`
239−
240−This `task` prints a `tape` to the dojo by first converting it from a UTF8
241−`tape` to a `list` of UTF32 codepoints (`@c`'s) and then recursively popping off a character from the
242−`tape` and sending it to to Unix to be printed into the terminal via a `%blit` event.
243−
244−#### Accepts
245−
246−```hoon
247−[p=tape]
248−```
249−
250−#### Returns
251−
252−This `task` returns zero or more `%blit` `gift`s, each containing a .
253−
254−
255−### `%trim`
256−
257−`%trim` is a common vane `task` used to reduce memory usage. However, it does
258−nothing for Dill.
259−
260−#### Accepts
261−
262−```hoon
263−[p=@ud]
264−```
265−
266−This is a common parameter for `%trim` `task`s across all vanes but does nothing
267−for Dill.
268−
269−#### Returns
270−
271−This `task` returns no `gift`s.
272−
273−
274−
275−### `%vega`
276−
277−This is a common vane `task` used to inform the vane that the kernel has been
278−upgraded. Dill does not do anything in response to this.
279−
280−#### Accepts
281−
282−```hoon
283−[ ~ ]
284−```
285−
286−#### Returns
287−
288−This `task` returns no `gift`s.
289−
290−
291−
292−## Arvo tasks
293−
294−These `task`s live in `task:able:dill` but are passed directly to the Arvo
295−kernel for processing.
296−
297−### `%lyra`
298−
299−This `task` updates the kernel.
300−
301−#### Accepts
302−
303−```hoon
304−[p=@t q=@t]
305−```
306−
307−`p` is the contents of the new `hoon.hoon` and `q` is the contents of the new `arvo.hoon`.
308−
309−#### Returns
310−
311−This `task` returns no `gift`s.
312−
313−
314−### `%pack`
315−
316−This `task` defragments and deduplicates Arvo's memory. This is ultimately
317−performed by the interpreter so you won't find the code in `arvo.hoon` but
318−rather under `c3__pack` in `urbit/worker/main.c`.
319−
320−#### Accepts
321−
322−```hoon
323−[ ~ ]
324−```
325−
326−#### Returns
327−
328−This `task` returns no `gift`s.
329−
330−
331−### `%veer`
332−
333−This `task` is used to install `zuse` and vanes. It is handled by `+veer` in
334−`arvo.hoon`.
335−
336−#### Accepts
337−
338−```hoon
339−[p=@ta q=path r=@t]
340−```
341−
342−`p` is the vane letter, `q` is the formal `path` to the
343−vane, and `r` is the source code for the vane. The vane letter is `%` followed
344−by the first letter of the vane in lowercase, such as `%d` for Dill. `p=%$` in
345−the case of `zuse`.
346−
347−#### Returns
348−
349−This `task` returns no `gift`s.
350−
351−
352−### `%verb`
353−
354−This `task` toggles verbose mode for all of Arvo, which is located here since
355−Dill is the vane that prints errors. To be precise, `%verb` toggles the laconic
356−bit `lac` in the [Arvo state](/docs/arvo/overview#the-state).
357−
358−#### Accepts
359−
360−```hoon
361−[ ~ ]
362−```
363−
364−#### Returns
365−
366−This `task` returns no `gift`s.