@@ -17,4 +17,667 @@ with changes, which useful for recursion among other things:
1717
1818## Runes
1919
20−;list(datapreview "true", classname "runes");
20+;=
21+ ;h3
22+ ;div(id "barcab"): |_ "barcab"
23+ ==
24+==
25+
26+Produce a *door* (a core with a sample).
27+
28+##### Syntax
29+
30+Regular:
31+
32+```
33+|_ a=spec
34+++ b=term c=hoon
35+++ d=term e=hoon
36+ ...
37+++ f=term g=hoon
38+--
39+```
40+
41+Note: The `++` rune may be replaced with any other rune in the `+` family.
42+
43+AST:
44+
45+```
46+[%brcb p=spec q=alas r=(map term tome)]
47+```
48+
49+##### Semantics
50+
51+The product of a `|_` expression is a *door*, a core with one or more arms whose payload includes a sample. That is, a door is a cell of `[battery [sample context]]`, where the `battery` contains one or more arms.
52+
53+`a` defines the door sample type and usually includes a name assignment (e.g., `n=@`). `a` is followed by a series of arm definitions, each of which begins with a rune in the `+` family (most of `++`). There must be at least one arm, but there may be arbitrarily many. Each arm must include a name (`b`, `d`, and `f` above), which is followed by the expression (`c`, `e`, and `g` above) that defines the arm product.
54+
55+The context of the door is the subject of the `|_` expression.
56+
57+##### Expands to
58+
59+```
60+=| a=spec
61+|%
62+++ b=term c=hoon
63+++ d=term e=hoon
64+ ...
65+++ f=term g=hoon
66+--
67+```
68+
69+##### Discussion
70+
71+A door is the general case of a gate (function). A gate is a
72+door with only one arm, which has the name `$`.
73+
74+Calling a door is like calling a gate except the caller also needs
75+to specify the arm to be computed. So, for example, if you have some door `door` which contains some arm `arm`, and you want to pass some argument (i.e., input value `arg`), you would call it with `~(arm door arg)`.
76+
77+Because gates are also doors, you can call them the same way. To call the gate `foo` as a door, instead of `(foo baz)` we would write `~($ foo baz)`. This
78+is an irregular form for `%~($ foo baz)`, [%~](/docs/reference/hoon-expressions/rune/cen#sig).
79+
80+##### Examples
81+
82+A trivial door:
83+
84+```
85+/~zod:dojo> =mol |_ a=@ud
86+ ++ succ +(a)
87+ ++ prev (dec a)
88+ --
89+/~zod:dojo> ~(succ mol 1)
90+2
91+/~zod:dojo> ~(succ mol ~(succ mol ~(prev mol 5)))
92+6
93+```
94+
95+A more interesting door, from the kernel library:
96+
97+```
98+++ ne
99+ |_ tig=@
100+ ++ d (add tig '0')
101+ ++ x ?:((gte tig 10) (add tig 87) d)
102+ ++ v ?:((gte tig 10) (add tig 87) d)
103+ ++ w ?:(=(tig 63) '~' ?:(=(tig 62) '-' ?:((gte tig 36) (add tig 29) x)))
104+ --
105+```
106+
107+The `ne` door prints a digit in base 10, 16, 32 or 64:
108+
109+```
110+~zod:dojo> `@t`~(x ne 12)
111+'c'
112+```
113+
114+;=
115+ ;h3
116+ ;div(id "barcen"): |% "barcen"
117+ ==
118+==
119+
120+Produce a core, `[battery payload]`.
121+
122+##### Syntax
123+
124+Regular:
125+
126+```
127+|%
128+++ a=term b=hoon
129+++ c=term d=hoon
130+ ...
131+++ e=term f=hoon
132+--
133+```
134+
135+Note: The `++` rune may be replaced with any other rune in the `+` family.
136+
137+AST:
138+
139+```
140+[%brcn p=(unit term) q=(map term tome)]
141+```
142+
143+##### Semantics
144+
145+The product of a `|%` expression is a dry core with one or more arms in the battery.
146+
147+The `|%` rune is followed by a series of arm definitions, each of which begins with a rune in the `+` family (most of `++`). There must be at least one arm, but there may be arbitrarily many. Each arm must include a name (`a`, `c`, and `e` above), which is followed by the expression (`b`, `d`, and `f` above) that defines the arm product.
148+
149+The core payload is the subject of the `|%` expression.
150+
151+##### Discussion
152+
153+A core is a cell of `[battery payload]`, where the `battery` is code and the `payload` is data. The `battery` is one or more arms. An arm is a computation that takes the core itself as its subject.
154+
155+The `|%` rune is used to construct a core from a series of arm definitions. Each arm definition in the expression begins with an arm rune (`++`, `+$`, or `+*`). These arms make up the `battery`. The subject of the `|%` expression is used to make the core's `payload`.
156+
157+A core is like an "object" in a conventional language, but its
158+attributes (_arms_) are functions on the core, not the core and
159+an argument. A "method" on a core is an arm that produces a gate.
160+
161+##### Examples
162+
163+A trivial core:
164+
165+```
166+~zod:dojo> =foo =+ x=58
167+ |%
168+ ++ n (add 42 x)
169+ ++ g |= b=@
170+ (add b n)
171+ --
172+~zod:dojo> n.foo
173+100
174+~zod:dojo> (g.foo 1)
175+101
176+```
177+
178+;=
179+ ;h3
180+ ;div(id "barcol"): |: "barcol"
181+ ==
182+==
183+
184+Produce a gate with a custom sample.
185+
186+##### Syntax
187+
188+Regular:
189+
190+```
191+|: a=hoon b=hoon
192+```
193+
194+AST:
195+
196+```
197+[%brcl p=hoon q=hoon]
198+```
199+
200+##### Semantics
201+
202+`a` is a Hoon expression whose product type defines which values the gate accepts, and it usually includes a name (e.g., `n=1`). The product of `a` also serves as the default value of the sample. `b` is a Hoon expression that determines the product value of the gate.
203+
204+##### Expands to
205+
206+```
207+=> ^~ a
208+ |. b
209+```
210+
211+##### Discussion
212+
213+Pick your own default value for the sample. Note that `a` is an ordinary expression, not a type; `|:` doesn't bunt a sample as
214+[`|=`](#bartis) does.
215+
216+This is useful if you want a gate to have a sample of a particular type, but you don't want the default value of the gate to be the default value of that type.
217+
218+##### Examples
219+
220+```
221+> =add-ten |:(n=`@`2 (add n 10))
222+
223+> (add-ten 10)
224+20
225+
226+> (add-ten)
227+12
228+```
229+
230+;=
231+ ;h3
232+ ;div(id "bardot"): |. "bardot"
233+ ==
234+==
235+
236+Produce a trap (a core with one arm `$`).
237+
238+##### Syntax
239+
240+Regular:
241+
242+```
243+|. a=hoon
244+```
245+
246+AST:
247+
248+```
249+[%brdt p=hoon]
250+```
251+
252+Semantics:
253+
254+A `|.` expression produces a core with a single arm, `$`. The core isn't explicitly given a sample. `a` is a Hoon expression that defines the computation of the `$` arm.
255+
256+The payload of the core is the subject of the `|.` expression.
257+
258+##### Expands to
259+
260+```
261+|% ++ $ a=hoon
262+--
263+```
264+
265+##### Discussion
266+
267+A trap is generally used to defer a computation.
268+
269+##### Examples
270+
271+A trivial trap:
272+
273+```
274+~zod:dojo> =foo |.(42)
275+
276+~zod:dojo> $:foo
277+42
278+
279+~zod:dojo> (foo)
280+42
281+```
282+
283+A more interesting trap:
284+
285+```
286+~zod:dojo> =foo =/ reps 10
287+ =/ step 0
288+ =/ outp 0
289+ |.
290+ ?: =(step reps)
291+ outp
292+ $(outp (add outp 2), step +(step))
293+~zod:dojo> (foo)
294+20
295+```
296+
297+Note that we can use `$()` to recurse back into the
298+trap, since it's a core with an `$` arm.
299+
300+> `$(...)` expands to `%=($ ...)` (["centis"](/docs/reference/hoon-expressions/rune/cen#centis)).
301+
302+;=
303+ ;h3
304+ ;div(id "barhep"): |- "barhep"
305+ ==
306+==
307+
308+Produce a trap (a core with one arm `$`) and evaluate it.
309+
310+##### Syntax
311+
312+Regular:
313+
314+```
315+|- a=hoon
316+```
317+
318+AST:
319+
320+```
321+[%brhp p=hoon]
322+```
323+
324+##### Semantics
325+
326+A `|-` expression produces a core with one arm named `$` and immediately evaluates `$`. `a` is a Hoon expression that determines what `$` evaluates to.
327+
328+##### Expands to
329+
330+```
331+=<($ |.(a=hoon))
332+```
333+
334+##### Discussion
335+
336+The `|-` rune can be thought of as a 'recursion point' or a 'loop starting point'. Since `|-` makes a `|.` (["bardot"](#bardot), a core with one arm named `$`, we can recurse back into it with `$()`.
337+
338+> `$(...)` expands to `%=($ ...)` (["centis"](/docs/reference/hoon-expressions/rune/cen#centis)).
339+
340+##### Examples
341+
342+A trivial computation doesn't recurse:
343+
344+```
345+~zod:dojo> |-(42)
346+42
347+```
348+
349+The classic loop is a decrement:
350+
351+```
352+~zod:dojo> =foo =/ a 42
353+ =/ b 0
354+ |-
355+ ?: =(a +(b))
356+ b
357+ $(b +(b))
358+~zod:dojo> foo
359+41
360+```
361+
362+;=
363+ ;h3
364+ ;div(id "barket"): |^ "barket"
365+ ==
366+==
367+
368+Produce a core whose battery includes a `$` arm and compute the latter.
369+
370+##### Syntax
371+
372+Regular:
373+
374+```
375+|^ a=hoon
376+++ b=term c=hoon
377+++ d=term e=hoon
378+ ...
379+++ f=term g=hoon
380+--
381+```
382+
383+Note: The `++` rune may be replaced with any other rune in the `+` family.
384+
385+AST:
386+
387+```
388+[%brkt p=hoon q=(map term tome)]
389+```
390+
391+##### Semantics
392+
393+A `|^` expression produces a multi-arm core whose battery includes a `$` arm, which is evaluated immediately. `a` is a Hoon expression that defines the product of the `$` arm. `a` is followed by a series of arm definitions for the rest of the core battery arms. There must be at least one arm other than the `$` arm.
394+
395+##### Expands to
396+
397+```
398+=> |%
399+ ++ $ a=hoon
400+ ++ b=term c=hoon
401+ ++ d=term e=hoon
402+ ...
403+ ++ f=term g=hoon
404+ --
405+$
406+```
407+
408+##### Discussion
409+
410+The `|^` rune is useful when you define a multi-arm core in your code and a particular arm in it is to be evaluated immediately.
411+
412+##### Examples
413+
414+A trivial example:
415+
416+```
417+~zod:dojo> |^
418+ (add n g)
419+ ++ n 42
420+ ++ g 58
421+ --
422+100
423+```
424+
425+;=
426+ ;h3
427+ ;div(id "barsig"): |~ "barsig"
428+ ==
429+==
430+
431+Produce an iron gate.
432+
433+##### Syntax
434+
435+Regular:
436+
437+```
438+|~ a=spec b=hoon
439+```
440+
441+AST:
442+
443+```
444+[%brsg p=spec q=hoon]
445+```
446+
447+##### Semantics
448+
449+A `|~` expression produces an iron gate. `a` defines the sample, and `b` defines the output value of the gate.
450+
451+##### Expands to
452+
453+```
454+^| |=(a b)
455+```
456+
457+##### Discussion
458+
459+See [this discussion of core variance models](/docs/reference/hoon-expressions/advanced)
460+
461+##### Examples
462+
463+```
464+~zod:dojo> => ~ ^+(|~(a=@ *@) |=(a=* *@))
465+<1|usl {a/@ $~}>
466+```
467+
468+;=
469+ ;h3
470+ ;div(id "bartar"): |* "bartar"
471+ ==
472+==
473+
474+Produce a wet gate (one-armed core with sample).
475+
476+##### Syntax
477+
478+Regular:
479+
480+```
481+|* a=spec b=hoon
482+```
483+
484+AST:
485+
486+```
487+[%brtr p=spec q=hoon]
488+```
489+
490+##### Semantics
491+
492+A `|*` expression produces a wet gate. `a` defines the gate's sample, and `b` is a Hoon expression that determines the output value of the gate.
493+
494+##### Expands to
495+
496+```
497+=| a
498+|@
499+++ $
500+ b
501+--
502+```
503+
504+##### Discussion
505+
506+In a normal (dry) gate, your argument is converted into the
507+sample type. In a generic (wet) gate, your argument type
508+passes through the function, rather as if it were a macro (there
509+is still only one copy of the code, however).
510+
511+Genericity is a powerful and dangerous tool. Use wet gates only if
512+you know what you're doing.
513+
514+Just as with a [gate](#bartis), we can recurse back into a wet gate
515+with `$()`.
516+
517+> `$(...)` expands to `%=($ ...)` (["centis"](/docs/reference/hoon-expressions/rune/cen#centis)).
518+
519+##### Examples
520+
521+Wet and dry gates in a nutshell:
522+
523+```
524+~zod:dojo> =foo |=([a=* b=*] [b a])
525+
526+~zod:dojo> =bar |*([a=* b=*] [b a])
527+
528+~zod:dojo> (foo %cat %dog)
529+[6.778.724 7.627.107]
530+
531+~zod:dojo> (bar %cat %dog)
532+[%dog %cat]
533+```
534+
535+The dry gate does not preserve the type of `a` and `b`; the wet
536+gate does.
537+
538+;=
539+ ;h3
540+ ;div(id "bartis"): |= "bartis"
541+ ==
542+==
543+
544+Produce a gate (a one-armed core with a sample).
545+
546+##### Syntax
547+
548+Regular:
549+
550+```
551+|= a=spec b=hoon
552+```
553+
554+AST:
555+
556+```
557+[%brts p=spec q=hoon]
558+```
559+
560+##### Definition
561+
562+The product of a `|=` expression is a dry *gate*, i.e., a Hoon function.
563+
564+`p` defines the gate sample type -- i.e., the input value type -- and usually includes a sample name assignment (e.g., `a=@`). `q` is an expression that determines the output value of the gate.
565+
566+##### Expands to
567+
568+```
569+=| a=spec
570+|% ++ $ b=hoon
571+--
572+```
573+
574+##### Discussion
575+
576+Dry gates are used for the vast majority of ordinary functions in Hoon.
577+
578+A gate is a core with one arm named `$`, so we can recurse back into it with `$()`.
579+
580+> `$(...)` expands to `%=($ ...)` (["centis"](/docs/reference/hoon-expressions/rune/cen#centis)).
581+
582+##### Examples
583+
584+A trivial gate:
585+
586+```
587+~zod:dojo> =foo |=(a=@ +(a))
588+
589+~zod:dojo> (foo 20)
590+21
591+```
592+
593+A slightly less trivial gate:
594+
595+```
596+~zod:dojo> =foo |= [a=@ b=@]
597+ (add a b)
598+~zod:dojo> (foo 30 400)
599+430
600+```
601+
602+;=
603+ ;h3
604+ ;div(id "barvat"): |@ "barvat"
605+ ==
606+==
607+
608+Produce a 'wet' core `[battery payload]`.
609+
610+##### Syntax
611+
612+Regular:
613+
614+```
615+|@
616+++ a=term b=hoon
617+++ c=term d=hoon
618+ ...
619+++ e=term f=hoon
620+--
621+```
622+
623+Note: The `++` rune may be replaced with any other rune in the `+` family.
624+
625+AST:
626+
627+```
628+[%brvt p=(unit term) q=(map term tome)]
629+```
630+
631+##### Semantics
632+
633+A `|@` expression produces a 'wet' core whose payload is the expression's subject. The various arms in the battery are each named (`a`, `c`, and `e` above) and defined explicitly with a Hoon expression (with `b`, `d`, and `f` above).
634+
635+##### Discussion
636+
637+The `|@` rune is just like the `|%` rune except that instead of producing a 'dry' core, it produces a 'wet' one. This allows for type polymorphism of its arms, using 'genericity'. See [Advanced types](/docs/reference/hoon-expressions/advanced).
638+
639+;=
640+ ;h3
641+ ;div(id "barwut"): |? "barwut"
642+ ==
643+==
644+
645+Produce a lead trap.
646+
647+##### Syntax
648+
649+Regular:
650+
651+```
652+|? a=hoon
653+```
654+
655+AST:
656+
657+```
658+[%brwt p=hoon]
659+```
660+
661+##### Semantics
662+
663+A `|?` expression produces a lead trap (i.e., a lead core with one arm named `$`). `a` is a Hoon expression that defines what the `$` arm does.
664+
665+##### Expands to
666+
667+```
668+^? |. a
669+```
670+
671+##### Discussion
672+
673+See this [discussion of the core variance model](/docs/reference/hoon-expressions/advanced).
674+
675+##### Examples
676+
677+```
678+~zod:dojo> => ~ ^+ |?(%a) |.(%a)
679+<1?pqz $~>
680+
681+~zod:dojo> => ~ ^+ |?(%a) |.(%b)
682+nest-fail
683+```