git.iko.soy/urbit.org
on master help sign in
rolled child rune-pages into parents. updates fakezod instructions in getting-started
337b3faRobert
getting-started.udon+3−1
compare with master
unifiedsplit
@@ -260,9 +260,11 @@ If you just want to use a fake ship for development purposes, you can now use
260the command of the scheme below to boot a fake `~zod`.
260the command of the scheme below to boot a fake `~zod`.
261
261
262```
262```
263−urbit -F zod -A /path/to/arvo -s -c zod
263+urbit -F zod
264```
264```
265
265
266+You can substitute any valid galaxy-, star-, or planet-name for `zod`.
267+
266If you want to get on the Arvo network with your point, then continue to the
268If you want to get on the Arvo network with your point, then continue to the
267next section.
269next section.
268
270
learn/arvo/arvo-internals/admin.udon−20
@@ -179,23 +179,3 @@ Urbit network.
179
179
180When this happens, back up any files you'd like to save, shut down your
180When this happens, back up any files you'd like to save, shut down your
181urbit and recreate it (as if you were starting for the first time).
181urbit and recreate it (as if you were starting for the first time).
182−
183−## Creating SSL certificates
184−
185−It is possible to create SSL certificates so that you serve files through your
186−ship's webserver using https. To do that you, would need a machine that has
187−OpenSSL installed. In order to create a new private key and a self-signed
188−certificate for your localhost, valid for a year, you can issue the following
189−commands:
190−
191−```
192−$ openssl req -x509 -sha256 -newkey rsa:4096 -keyout private.pem -out certificate.pem -subj '/CN=localhost' -days 365
193−$ mkdir -p your-urbit/.urb/tls
194−$ mv private.pem certificate.pem your-urbit/.urb/tls
195−```
196−
197−These certificates would have to be manually trusted by your browser, and it's
198−advisable that they are used only for your localhost.
199−For public-facing webservers, it would be better to create certificates for your
200−fully qualified domain name using a trusted certificate authority like Let's
201−Encrypt.
reference/hoon-expressions/rune/bar.udon+664−1
@@ -17,4 +17,667 @@ with changes, which useful for recursion among other things:
17
17
18## Runes
18## Runes
19
19
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+```
reference/hoon-expressions/rune/bar/cab.udondeleted−96
@@ -1,96 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'5'
4− title/'|_ "barcab"'
5− ==
6−;>
7−
8−# `|_ "barcab"`
9−
10−Produce a *door* (a core with a sample).
11−
12−## Syntax
13−
14−Regular:
15−
16−```
17−|_ a=spec
18−++ b=term c=hoon
19−++ d=term e=hoon
20− ...
21−++ f=term g=hoon
22−--
23−```
24−
25−Note: The `++` rune may be replaced with any other rune in the `+` family.
26−
27−AST:
28−
29−```
30−[%brcb p=spec q=alas r=(map term tome)]
31−```
32−
33−## Semantics
34−
35−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.
36−
37−`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.
38−
39−The context of the door is the subject of the `|_` expression.
40−
41−## Expands to
42−
43−```
44−=| a=spec
45−|%
46−++ b=term c=hoon
47−++ d=term e=hoon
48− ...
49−++ f=term g=hoon
50−--
51−```
52−
53−## Discussion
54−
55−A door is the general case of a gate (function). A gate is a
56−door with only one arm, which has the name `$`.
57−
58−Calling a door is like calling a gate except the caller also needs
59−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)`.
60−
61−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
62−is an irregular form for `%~($ foo baz)`, [%~](../../cen/sig).
63−
64−## Examples
65−
66−A trivial door:
67−
68−```
69−/~zod:dojo> =mol |_ a=@ud
70− ++ succ +(a)
71− ++ prev (dec a)
72− --
73−/~zod:dojo> ~(succ mol 1)
74−2
75−/~zod:dojo> ~(succ mol ~(succ mol ~(prev mol 5)))
76−6
77−```
78−
79−A more interesting door, from the kernel library:
80−
81−```
82−++ ne
83− |_ tig=@
84− ++ d (add tig '0')
85− ++ x ?:((gte tig 10) (add tig 87) d)
86− ++ v ?:((gte tig 10) (add tig 87) d)
87− ++ w ?:(=(tig 63) '~' ?:(=(tig 62) '-' ?:((gte tig 36) (add tig 29) x)))
88− --
89−```
90−
91−The `ne` door prints a digit in base 10, 16, 32 or 64:
92−
93−```
94−~zod:dojo> `@t`~(x ne 12)
95−'c'
96−```
reference/hoon-expressions/rune/bar/cen.udondeleted−66
@@ -1,66 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'1'
4− title/'|% "barcen"'
5− ==
6−;>
7−
8−# `|% "barcen"`
9−
10−Produce a core, `[battery payload]`.
11−
12−## Syntax
13−
14−Regular:
15−
16−```
17−|%
18−++ a=term b=hoon
19−++ c=term d=hoon
20− ...
21−++ e=term f=hoon
22−--
23−```
24−
25−Note: The `++` rune may be replaced with any other rune in the `+` family.
26−
27−AST:
28−
29−```
30−[%brcn p=(unit term) q=(map term tome)]
31−```
32−
33−## Semantics
34−
35−The product of a `|%` expression is a dry core with one or more arms in the battery.
36−
37−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.
38−
39−The core payload is the subject of the `|%` expression.
40−
41−## Discussion
42−
43−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.
44−
45−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`.
46−
47−A core is like an "object" in a conventional language, but its
48−attributes (_arms_) are functions on the core, not the core and
49−an argument. A "method" on a core is an arm that produces a gate.
50−
51−## Examples
52−
53−A trivial core:
54−
55−```
56−~zod:dojo> =foo =+ x=58
57− |%
58− ++ n (add 42 x)
59− ++ g |= b=@
60− (add b n)
61− --
62−~zod:dojo> n.foo
63−100
64−~zod:dojo> (g.foo 1)
65−101
66−```
reference/hoon-expressions/rune/bar/col.udondeleted−54
@@ -1,54 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'9'
4− title/'|: "barcol"'
5− ==
6−;>
7−
8−# `|: "barcol"`
9−
10−Produce a gate with a custom sample.
11−
12−## Syntax
13−
14−Regular:
15−
16−```
17−|: a=hoon b=hoon
18−```
19−
20−AST:
21−
22−```
23−[%brcl p=hoon q=hoon]
24−```
25−
26−## Semantics
27−
28−`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.
29−
30−## Expands to
31−
32−```
33−=> ^~ a
34− |. b
35−```
36−
37−## Discussion
38−
39−Pick your own default value for the sample. Note that `a` is an ordinary expression, not a type; `|:` doesn't bunt a sample as
40−[`|=`](../tis) does.
41−
42−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.
43−
44−## Examples
45−
46−```
47−> =add-ten |:(n=`@`2 (add n 10))
48−
49−> (add-ten 10)
50−20
51−
52−> (add-ten)
53−12
54−```
reference/hoon-expressions/rune/bar/dot.udondeleted−74
@@ -1,74 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'6'
4− title/'|. "bardot"'
5− ==
6−;>
7−
8−# `|. "bardot"`
9−
10−Produce a trap (a core with one arm `$`).
11−
12−## Syntax
13−
14−Regular:
15−
16−```
17−|. a=hoon
18−```
19−
20−AST:
21−
22−```
23−[%brdt p=hoon]
24−```
25−
26−Semantics:
27−
28−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.
29−
30−The payload of the core is the subject of the `|.` expression.
31−
32−## Expands to
33−
34−```
35−|% ++ $ a=hoon
36−--
37−```
38−
39−## Discussion
40−
41−A trap is generally used to defer a computation.
42−
43−## Examples
44−
45−A trivial trap:
46−
47−```
48−~zod:dojo> =foo |.(42)
49−
50−~zod:dojo> $:foo
51−42
52−
53−~zod:dojo> (foo)
54−42
55−```
56−
57−A more interesting trap:
58−
59−```
60−~zod:dojo> =foo =/ reps 10
61− =/ step 0
62− =/ outp 0
63− |.
64− ?: =(step reps)
65− outp
66− $(outp (add outp 2), step +(step))
67−~zod:dojo> (foo)
68−20
69−```
70−
71−Note that we can use `$()` to recurse back into the
72−trap, since it's a core with an `$` arm.
73−
74−> `$(...)` expands to `%=($ ...)` (["centis"](../../cen/tis)).
reference/hoon-expressions/rune/bar/hep.udondeleted−62
@@ -1,62 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'7'
4− title/'|- "barhep"'
5− ==
6−;>
7−
8−# `|- "barhep"`
9−
10−Produce a trap (a core with one arm `$`) and evaluate it.
11−
12−## Syntax
13−
14−Regular:
15−
16−```
17−|- a=hoon
18−```
19−
20−AST:
21−
22−```
23−[%brhp p=hoon]
24−```
25−
26−## Semantics
27−
28−A `|-` expression produces a core with one arm named `$` and immediately evaluates `$`. `a` is a Hoon expression that determines what `$` evaluates to.
29−
30−## Expands to
31−
32−```
33−=<($ |.(a=hoon))
34−```
35−
36−## Discussion
37−
38−The `|-` rune can be thought of as a 'recursion point' or a 'loop starting point'. Since `|-` makes a `|.` (["bardot"](../dot), a core with one arm named `$`, we can recurse back into it with `$()`.
39−
40−> `$(...)` expands to `%=($ ...)` (["centis"](../../cen/tis)).
41−
42−## Examples
43−
44−A trivial computation doesn't recurse:
45−
46−```
47−~zod:dojo> |-(42)
48−42
49−```
50−
51−The classic loop is a decrement:
52−
53−```
54−~zod:dojo> =foo =/ a 42
55− =/ b 0
56− |-
57− ?: =(a +(b))
58− b
59− $(b +(b))
60−~zod:dojo> foo
61−41
62−```
reference/hoon-expressions/rune/bar/ket.udondeleted−65
@@ -1,65 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'8'
4− title/'|^ "barket"'
5− ==
6−;>
7−
8−# `|^ "barket"`
9−
10−Produce a core whose battery includes a `$` arm and compute the latter.
11−
12−## Syntax
13−
14−Regular:
15−
16−```
17−|^ a=hoon
18−++ b=term c=hoon
19−++ d=term e=hoon
20− ...
21−++ f=term g=hoon
22−--
23−```
24−
25−Note: The `++` rune may be replaced with any other rune in the `+` family.
26−
27−AST:
28−
29−```
30−[%brkt p=hoon q=(map term tome)]
31−```
32−
33−## Semantics
34−
35−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.
36−
37−## Expands to
38−
39−```
40−=> |%
41− ++ $ a=hoon
42− ++ b=term c=hoon
43− ++ d=term e=hoon
44− ...
45− ++ f=term g=hoon
46− --
47−$
48−```
49−
50−## Discussion
51−
52−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.
53−
54−## Examples
55−
56−A trivial example:
57−
58−```
59−~zod:dojo> |^
60− (add n g)
61− ++ n 42
62− ++ g 58
63− --
64−100
65−```
reference/hoon-expressions/rune/bar/sig.udondeleted−45
@@ -1,45 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'2'
4− title/'|~ "barsig"'
5− ==
6−;>
7−
8−# `|~ "barsig"`
9−
10−Produce an iron gate.
11−
12−## Syntax
13−
14−Regular:
15−
16−```
17−|~ a=spec b=hoon
18−```
19−
20−AST:
21−
22−```
23−[%brsg p=spec q=hoon]
24−```
25−
26−## Semantics
27−
28−A `|~` expression produces an iron gate. `a` defines the sample, and `b` defines the output value of the gate.
29−
30−## Expands to
31−
32−```
33−^| |=(a b)
34−```
35−
36−## Discussion
37−
38−See [this discussion of core variance models](../../../advanced)
39−
40−## Examples
41−
42−```
43−~zod:dojo> => ~ ^+(|~(a=@ *@) |=(a=* *@))
44−<1|usl {a/@ $~}>
45−```
reference/hoon-expressions/rune/bar/tar.udondeleted−72
@@ -1,72 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'10'
4− title/'|* "bartar"'
5− ==
6−;>
7−
8−# `|* "bartar"`
9−
10−Produce a wet gate (one-armed core with sample).
11−
12−## Syntax
13−
14−Regular:
15−
16−```
17−|* a=spec b=hoon
18−```
19−
20−AST:
21−
22−```
23−[%brtr p=spec q=hoon]
24−```
25−
26−## Semantics
27−
28−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.
29−
30−## Expands to
31−
32−```
33−=| a
34−|@
35−++ $
36− b
37−--
38−```
39−
40−## Discussion
41−
42−In a normal (dry) gate, your argument is converted into the
43−sample type. In a generic (wet) gate, your argument type
44−passes through the function, rather as if it were a macro (there
45−is still only one copy of the code, however).
46−
47−Genericity is a powerful and dangerous tool. Use wet gates only if
48−you know what you're doing.
49−
50−Just as with a [gate](../tis), we can recurse back into a wet gate
51−with `$()`.
52−
53−> `$(...)` expands to `%=($ ...)` (["centis"](../../cen/tis)).
54−
55−## Examples
56−
57−Wet and dry gates in a nutshell:
58−
59−```
60−~zod:dojo> =foo |=([a=* b=*] [b a])
61−
62−~zod:dojo> =bar |*([a=* b=*] [b a])
63−
64−~zod:dojo> (foo %cat %dog)
65−[6.778.724 7.627.107]
66−
67−~zod:dojo> (bar %cat %dog)
68−[%dog %cat]
69−```
70−
71−The dry gate does not preserve the type of `a` and `b`; the wet
72−gate does.
reference/hoon-expressions/rune/bar/tis.udondeleted−66
@@ -1,66 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'4'
4− title/'|= "bartis"'
5− ==
6−;>
7−
8−# `|= "bartis"`
9−
10−Produce a gate (a one-armed core with a sample).
11−
12−## Syntax
13−
14−Regular:
15−
16−```
17−|= a=spec b=hoon
18−```
19−
20−AST:
21−
22−```
23−[%brts p=spec q=hoon]
24−```
25−
26−## Definition
27−
28−The product of a `|=` expression is a dry *gate*, i.e., a Hoon function.
29−
30−`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.
31−
32−## Expands to
33−
34−```
35−=| a=spec
36−|% ++ $ b=hoon
37−--
38−```
39−
40−## Discussion
41−
42−Dry gates are used for the vast majority of ordinary functions in Hoon.
43−
44−A gate is a core with one arm named `$`, so we can recurse back into it with `$()`.
45−
46−> `$(...)` expands to `%=($ ...)` (["centis"](../../cen/tis)).
47−
48−## Examples
49−
50−A trivial gate:
51−
52−```
53−~zod:dojo> =foo |=(a=@ +(a))
54−
55−~zod:dojo> (foo 20)
56−21
57−```
58−
59−A slightly less trivial gate:
60−
61−```
62−~zod:dojo> =foo |= [a=@ b=@]
63− (add a b)
64−~zod:dojo> (foo 30 400)
65−430
66−```
reference/hoon-expressions/rune/bar/vat.udondeleted−39
@@ -1,39 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'11'
4− title/'|@ "barvat"'
5− ==
6−;>
7−
8−# `|@ "barvat"`
9−
10−Produce a 'wet' core `[battery payload]`.
11−
12−## Syntax
13−
14−Regular:
15−
16−```
17−|@
18−++ a=term b=hoon
19−++ c=term d=hoon
20− ...
21−++ e=term f=hoon
22−--
23−```
24−
25−Note: The `++` rune may be replaced with any other rune in the `+` family.
26−
27−AST:
28−
29−```
30−[%brvt p=(unit term) q=(map term tome)]
31−```
32−
33−## Semantics
34−
35−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).
36−
37−## Discussion
38−
39−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](../../../advanced).
reference/hoon-expressions/rune/bar/wut.udondeleted−48
@@ -1,48 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'3'
4− title/'|? "barwut"'
5− ==
6−;>
7−
8−# `|? "barwut"`
9−
10−Produce a lead trap.
11−
12−## Syntax
13−
14−Regular:
15−
16−```
17−|? a=hoon
18−```
19−
20−AST:
21−
22−```
23−[%brwt p=hoon]
24−```
25−
26−## Semantics
27−
28−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.
29−
30−## Expands to
31−
32−```
33−^? |. a
34−```
35−
36−## Discussion
37−
38−See this [discussion of the core variance model](../../../advanced).
39−
40−## Examples
41−
42−```
43−~zod:dojo> => ~ ^+ |?(%a) |.(%a)
44−<1?pqz $~>
45−
46−~zod:dojo> => ~ ^+ |?(%a) |.(%b)
47−nest-fail
48−```
reference/hoon-expressions/rune/bus.udon+397−1
@@ -36,6 +36,402 @@ instance, `(map foo bar)` is a table from mold `foo` to mold
36`bar`. `map` is not a mold; it's a function that makes a mold.
36`bar`. `map` is not a mold; it's a function that makes a mold.
37Molds and mold builders are generally described together.
37Molds and mold builders are generally described together.
38
38
39+;=
40+ ;h2
41+ ;div(id "base"): Base Structures
42+ ==
43+==
44+
45+`[%base p=$@(?(%noun %cell %bean %null) [%atom p=aura])]`: trivial structures (types).
46+
47+##### Produces
48+
49+A structure is a noun produced, usually at compile-time, for use in tracking types. In most cases, structures don't exist in the runtime semantics.
50+
51+A structure for the base in `p`. `%noun` is any noun; `%atom` is any
52+atom; `%cell` is a cell of nouns; `%flag` is a loobean, ``?(`@f`0
53+`@f`1)``. `%null` is zero with aura `@n`.
54+
55+##### Syntax
56+
57+Irregular: `*` makes `%noun`, `^` makes `%cell`, `?` makes
58+`%bean`, `~` makes `%null`, `@aura` makes atom `aura`.
59+
39## Runes
60## Runes
40
61
41−;list(datapreview "true", classname "runes");
62+;=
63+ ;h3
64+ ;div(id "buscab"): $_ "buscab"
65+ ==
66+==
67+
68+`[%bscb p=hoon]`: structure that normalizes to an example.
69+
70+##### Expands to
71+
72+```
73+|=(* p)
74+```
75+
76+##### Syntax
77+
78+Regular: *1-fixed*.
79+
80+Irregular: `_foo` is `$_(foo)`.
81+
82+##### Discussion
83+
84+`$_` discards the sample it's supposedly normalizing
85+and produces its *example* instead.
86+
87+##### Examples
88+
89+```
90+~zod:dojo> =foo $_([%foobaz %moobaz])
91+
92+~zod:dojo> (foo %foo %baz)
93+[%foobaz %moobaz]
94+
95+~zod:dojo> `foo`[%foobaz %moobaz]
96+[%foobaz %moobaz]
97+
98+~zod:dojo $:foo
99+[%foobaz %moobaz]
100+```
101+
102+;=
103+ ;h3
104+ ;div(id "buscen"): $% "buscen"
105+ ==
106+==
107+
108+`[%bscn p=(list spec)]`: structure which recognizes a union tagged by head atom.
109+
110+##### Defaults to
111+
112+The default of the last item `i` in `p`. Crashes if `p` is empty.
113+
114+##### Syntax
115+
116+Regular form: *2-running*.
117+
118+##### Discussion
119+
120+A `$%` is a tagged union, a common data model.
121+
122+Make sure the first item in your `$%` terminates, or the default will
123+be an infinite loop!
124+
125+##### Examples
126+
127+```
128+~zod:dojo> =foo $%([%foo p=@ud q=@ud] [%baz p=@ud])
129+
130+~zod:dojo> (foo [%baz 37])
131+[%baz p=37]
132+
133+~zod:dojo> $:foo
134+[%foo p=0 q=0]~
135+```
136+
137+;=
138+ ;h3
139+ ;div(id "buscol"): $: "buscol"
140+ ==
141+==
142+
143+`[%bscl p=(list spec)]`: form a cell type.
144+
145+##### Normalizes
146+
147+The tuple the length of `p`, normalizing each item.
148+
149+##### Defaults to
150+
151+The tuple the length of `p`.
152+
153+##### Syntax
154+
155+Regular: *running*.
156+
157+Irregular (noun mode): `,[a b c]` is `$:(a b c)`.
158+Irregular (structure mode): `[a b c]` is `$:(a b c)`.
159+
160+##### Examples
161+
162+```
163+~zod:dojo> =foo $:(p=@ud q=@tas)
164+
165+~zod:dojo> (foo 33 %foo)
166+[p=33 q=%foo]
167+
168+~zod:dojo> `foo`[33 %foo]
169+[p=33 q=%foo]
170+
171+~zod:dojo> $:foo
172+[p=0 q=%$]
173+```
174+
175+;=
176+ ;h3
177+ ;div(id "bushep"): $- "bushep"
178+ ==
179+==
180+
181+`[%bshp p=spec q=spec]`: structure that normalizes to an example gate.
182+
183+##### Expands to
184+
185+```
186+$_ ^|
187+|=(p $:q)
188+```
189+
190+##### Syntax
191+
192+Regular: *2-fixed*.
193+
194+##### Discussion
195+
196+Since a `$-` reduces to a [`$_`](#buscab), it is not useful for normalizing, just for typechecking. In particular, the existence of `$-`s does *not* let us send gates or other cores over the network!
197+
198+##### Examples
199+
200+```
201+~zod:dojo> =foo $-(%foo %baz)
202+
203+~zod:dojo> ($:foo %foo)
204+%baz
205+```
206+
207+;=
208+ ;h3
209+ ;div(id "busket"): $^ "busket"
210+ ==
211+==
212+
213+`[%bskt p=spec q=spec]`: structure which normalizes a union tagged by head depth (cell).
214+
215+##### Normalizes to
216+
217+Default, if the sample is an atom; `p`, if the head of the sample
218+is an atom; `q` otherwise.
219+
220+##### Defaults to
221+
222+The default of `p`.
223+
224+##### Syntax
225+
226+Regular: *2-fixed*.
227+
228+##### Examples
229+
230+```
231+~zod:dojo> =a $%([%foo p=@ud q=@ud] [%baz p=@ud])
232+
233+~zod:dojo> =b $^([a a] a)
234+
235+~zod:dojo> (b [[%baz 33] [%foo 19 22]])
236+[[%baz p=33] [%foo p=19 q=22]]
237+
238+~zod:dojo> (b [%foo 19 22])
239+[%foo p=19 q=22]
240+
241+~zod:dojo> $:b
242+[%baz p=0]
243+```
244+
245+;=
246+ ;h3
247+ ;div(id "bussig"): $~ "bussig"
248+ ==
249+==
250+
251+`[%bssg p=hoon q=spec]`: define a custom type default value
252+
253+## Product
254+
255+Creates a structure (custom type) just like `q`, except its default value is `p`.
256+
257+##### Defaults to
258+
259+The product of `p`.
260+
261+##### Syntax
262+
263+Regular: *2-fixed*.
264+
265+```
266+$~ p=hoon q=spec
267+```
268+
269+`p` defines the default value, and `q` defines everything else about the structure.
270+
271+##### Discussion
272+
273+You should make sure that the product type of `p` nests under `q`. You can check the default value of some structure (custom type) `r` with `*r`. (See the [`^*` rune](/docs/reference/hoon-expressions/rune/ket#kettar).)
274+
275+Do not confuse the `$~` rune with the constant type for null, `$~`. (The latter uses older Hoon syntax that is still accepted. Preferably it would be `%~`.)
276+
277+##### Examples
278+
279+First, let's define a type without using `$~`:
280+
281+```
282+> =b $@(@tas $%([%two *] [%three *]))
283+
284+> `b`%hello
285+%hello
286+
287+> `b`[%two %hello]
288+[%two 478.560.413.032]
289+
290+> *b
291+%$
292+
293+> *@tas
294+%$
295+```
296+
297+Using `$~`:
298+
299+```
300+> =c $~(%default-value $@(@tas $%([%two *] [%three *])))
301+
302+> `c`%hello
303+%hello
304+
305+> `c`[%two %hello]
306+[%two 478.560.413.032]
307+
308+> *c
309+%default-value
310+```
311+
312+;=
313+ ;h3
314+ ;div(id "busvat"): $@ "busvat"
315+ ==
316+==
317+
318+`[%bsvt p=spec q=spec]`: structure which normalizes a union tagged by head depth (atom).
319+
320+###### Normalizes to
321+
322+Default, if the sample is an atom; `p`, if the head of the sample
323+is an atom; `q` otherwise.
324+
325+##### Defaults to
326+
327+The default of `p`.
328+
329+#### Syntax
330+
331+Regular: *2-fixed*.
332+
333+Product: a structure which applies `p` if its sample is an atom,
334+`q` if its sample is a cell.
335+
336+Regular form: *2-fixed*.
337+
338+Example:
339+
340+```
341+~zod:dojo> =a $@(%foo $:(p=%baz q=@ud))
342+
343+~zod:dojo> (a %foo)
344+%foo
345+
346+~zod:dojo> `a`[%baz 99]
347+[p=%baz q=99]
348+
349+~zod:dojo> $:a
350+[%foo p=0 q=0]
351+```
352+
353+
354+;=
355+ ;h3
356+ ;div(id "bustis"): $= "bustis"
357+ ==
358+==
359+
360+`[%bsts p=skin q=spec]`: structure which wraps a face around another structure.
361+
362+##### Expands to
363+
364+```
365+|= *
366+^=(p %-(q +6))
367+```
368+
369+##### Syntax
370+
371+Regular: *2-fixed*.
372+
373+Irregular (structure mode): `foo=baz` is `$=(foo baz)`.
374+
375+##### Discussion
376+
377+Note that the Hoon compiler is at least slightly clever about
378+compiling structures, and almost never has to actually put in a gate
379+layer (as seen in the expansion above) to apply a `$=`.
380+
381+##### Examples
382+
383+```
384+~zod:dojo> =a $=(p %foo)
385+
386+~zod:dojo> (a %foo)
387+p=%foo
388+
389+~zod:dojo> (a %baz)
390+p=%foo
391+```
392+
393+;=
394+ ;h3
395+ ;div(id "buswut"): $? "buswut"
396+ ==
397+==
398+
399+`[%bswt p=(list spec)]`: form a type from a union of other types.
400+
401+###### Normalizes to
402+
403+The first item in `p` which normalizes the sample to itself.
404+
405+Void, if `p` is empty.
406+
407+##### Defaults to
408+
409+The first item in `p`.
410+
411+##### Syntax
412+
413+Regular: *running*.
414+
415+Irregular: `?(%foo %baz)` is `$?(%foo %baz)`.
416+
417+##### Discussion
418+
419+For a union of atoms, a `$?` is fine. For more complex nouns,
420+always try to use a [`$%`](#buscen), [`$@`](#busvat) or
421+[`$^`](#bushep), at least if you expect your structure to be used as a
422+normalizer.
423+
424+##### Examples
425+
426+```
427+~zod:dojo> =a ?(%foo %baz %baz)
428+
429+~zod:dojo> (a %baz)
430+%baz
431+
432+~zod:dojo> (a [37 45])
433+%baz
434+
435+~zod:dojo> $:a
436+%baz
437+```
reference/hoon-expressions/rune/bus/base.udondeleted−23
@@ -1,23 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'1'
4− title/'Base Structures'
5− ==
6−;>
7−
8−# Base Structures
9−
10−`[%base p=$@(?(%noun %cell %bean %null) [%atom p=aura])]`: trivial structures (types).
11−
12−## Produces
13−
14−A structure is a noun produced, usually at compile-time, for use in tracking types. In most cases, structures don't exist in the runtime semantics.
15−
16−A structure for the base in `p`. `%noun` is any noun; `%atom` is any
17−atom; `%cell` is a cell of nouns; `%flag` is a loobean, ``?(`@f`0
18−`@f`1)``. `%null` is zero with aura `@n`.
19−
20−## Syntax
21−
22−Irregular: `*` makes `%noun`, `^` makes `%cell`, `?` makes
23−`%bean`, `~` makes `%null`, `@aura` makes atom `aura`.
reference/hoon-expressions/rune/bus/cab.udondeleted−42
@@ -1,42 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'9'
4− title/'$_ "buscab"'
5− ==
6−;>
7−
8−# `$_ "buscab"`
9−
10−`[%bscb p=hoon]`: structure that normalizes to an example.
11−
12−## Expands to
13−
14−```
15−|=(* p)
16−```
17−
18−## Syntax
19−
20−Regular: *1-fixed*.
21−
22−Irregular: `_foo` is `$_(foo)`.
23−
24−## Discussion
25−
26−`$_` discards the sample it's supposedly normalizing
27−and produces its *example* instead.
28−
29−## Examples
30−
31−```
32−~zod:dojo> =foo $_([%foobaz %moobaz])
33−
34−~zod:dojo> (foo %foo %baz)
35−[%foobaz %moobaz]
36−
37−~zod:dojo> `foo`[%foobaz %moobaz]
38−[%foobaz %moobaz]
39−
40−~zod:dojo $:foo
41−[%foobaz %moobaz]
42−```
reference/hoon-expressions/rune/bus/cen.udondeleted−37
@@ -1,37 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'5'
4− title/'$% "buscen"'
5− ==
6−;>
7−
8−# `$% "buscen"`
9−
10−`[%bscn p=(list spec)]`: structure which recognizes a union tagged by head atom.
11−
12−## Defaults to
13−
14−The default of the last item `i` in `p`. Crashes if `p` is empty.
15−
16−## Syntax
17−
18−Regular form: *2-running*.
19−
20−## Discussion
21−
22−A `$%` is a tagged union, a common data model.
23−
24−Make sure the first item in your `$%` terminates, or the default will
25−be an infinite loop!
26−
27−## Examples
28−
29−```
30−~zod:dojo> =foo $%([%foo p=@ud q=@ud] [%baz p=@ud])
31−
32−~zod:dojo> (foo [%baz 37])
33−[%baz p=37]
34−
35−~zod:dojo> $:foo
36−[%foo p=0 q=0]~
37−```
reference/hoon-expressions/rune/bus/col.udondeleted−40
@@ -1,40 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'3'
4− title/'$: "buscol"'
5− ==
6−;>
7−
8−# `$: "buscol"`
9−
10−`[%bscl p=(list spec)]`: form a cell type.
11−
12−## Normalizes
13−
14−The tuple the length of `p`, normalizing each item.
15−
16−## Defaults to
17−
18−The tuple the length of `p`.
19−
20−## Syntax
21−
22−Regular: *running*.
23−
24−Irregular (noun mode): `,[a b c]` is `$:(a b c)`.
25−Irregular (structure mode): `[a b c]` is `$:(a b c)`.
26−
27−## Examples
28−
29−```
30−~zod:dojo> =foo $:(p=@ud q=@tas)
31−
32−~zod:dojo> (foo 33 %foo)
33−[p=33 q=%foo]
34−
35−~zod:dojo> `foo`[33 %foo]
36−[p=33 q=%foo]
37−
38−~zod:dojo> $:foo
39−[p=0 q=%$]
40−```
reference/hoon-expressions/rune/bus/hep.udondeleted−34
@@ -1,34 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'2'
4− title/'$- "bushep"'
5− ==
6−;>
7−
8−# `$- "buchep"`
9−
10−`[%bshp p=spec q=spec]`: structure that normalizes to an example gate.
11−
12−## Expands to
13−
14−```
15−$_ ^|
16−|=(p $:q)
17−```
18−
19−## Syntax
20−
21−Regular: *2-fixed*.
22−
23−## Discussion
24−
25−Since a `$-` reduces to a [`$_`](../cab/), it is not useful for normalizing, just for typechecking. In particular, the existence of `$-`s does *not* let us send gates or other cores over the network!
26−
27−## Examples
28−
29−```
30−~zod:dojo> =foo $-(%foo %baz)
31−
32−~zod:dojo> ($:foo %foo)
33−%baz
34−```
reference/hoon-expressions/rune/bus/ket.udondeleted−40
@@ -1,40 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'7'
4− title/'$^ "busket"'
5− ==
6−;>
7−
8−# `$^ "busket"`
9−
10−`[%bskt p=spec q=spec]`: structure which normalizes a union tagged by head depth (cell).
11−
12−## Normalizes to
13−
14−Default, if the sample is an atom; `p`, if the head of the sample
15−is an atom; `q` otherwise.
16−
17−## Defaults to
18−
19−The default of `p`.
20−
21−## Syntax
22−
23−Regular: *2-fixed*.
24−
25−## Examples
26−
27−```
28−~zod:dojo> =a $%([%foo p=@ud q=@ud] [%baz p=@ud])
29−
30−~zod:dojo> =b $^([a a] a)
31−
32−~zod:dojo> (b [[%baz 33] [%foo 19 22]])
33−[[%baz p=33] [%foo p=19 q=22]]
34−
35−~zod:dojo> (b [%foo 19 22])
36−[%foo p=19 q=22]
37−
38−~zod:dojo> $:b
39−[%baz p=0]
40−```
reference/hoon-expressions/rune/bus/sig.udondeleted−69
@@ -1,69 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'10'
4− title/'$~ "bussig"'
5− ==
6−;>
7−
8−# `$~ "bussig"`
9−
10−`[%bssg p=hoon q=spec]`: define a custom type default value
11−
12−## Product
13−
14−Creates a structure (custom type) just like `q`, except its default value is `p`.
15−
16−## Defaults to
17−
18−The product of `p`.
19−
20−## Syntax
21−
22−Regular: *2-fixed*.
23−
24−```
25−$~ p=hoon q=spec
26−```
27−
28−`p` defines the default value, and `q` defines everything else about the structure.
29−
30−## Discussion
31−
32−You should make sure that the product type of `p` nests under `q`. You can check the default value of some structure (custom type) `r` with `*r`. (See the [`^*` rune](../../ket/tar).)
33−
34−Do not confuse the `$~` rune with the constant type for null, `$~`. (The latter uses older Hoon syntax that is still accepted. Preferably it would be `%~`.)
35−
36−## Examples
37−
38−First, let's define a type without using `$~`:
39−
40−```
41−> =b $@(@tas $%([%two *] [%three *]))
42−
43−> `b`%hello
44−%hello
45−
46−> `b`[%two %hello]
47−[%two 478.560.413.032]
48−
49−> *b
50−%$
51−
52−> *@tas
53−%$
54−```
55−
56−Using `$~`:
57−
58−```
59−> =c $~(%default-value $@(@tas $%([%two *] [%three *])))
60−
61−> `c`%hello
62−%hello
63−
64−> `c`[%two %hello]
65−[%two 478.560.413.032]
66−
67−> *c
68−%default-value
69−```
reference/hoon-expressions/rune/bus/tis.udondeleted−41
@@ -1,41 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'8'
4− title/'$= "bustis"'
5− ==
6−;>
7−
8−# `$= "bustis"`
9−
10−`[%bsts p=skin q=spec]`: structure which wraps a face around another structure.
11−
12−## Expands to
13−
14−```
15−|= *
16−^=(p %-(q +6))
17−```
18−
19−## Syntax
20−
21−Regular: *2-fixed*.
22−
23−Irregular (structure mode): `foo=baz` is `$=(foo baz)`.
24−
25−## Discussion
26−
27−Note that the Hoon compiler is at least slightly clever about
28−compiling structures, and almost never has to actually put in a gate
29−layer (as seen in the expansion above) to apply a `$=`.
30−
31−## Examples
32−
33−```
34−~zod:dojo> =a $=(p %foo)
35−
36−~zod:dojo> (a %foo)
37−p=%foo
38−
39−~zod:dojo> (a %baz)
40−p=%foo
41−```
reference/hoon-expressions/rune/bus/vat.udondeleted−43
@@ -1,43 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'6'
4− title/'$@ "busvat"'
5− ==
6−;>
7−
8−# `$@ "busvat"`
9−
10−`[%bsvt p=spec q=spec]`: structure which normalizes a union tagged by head depth (atom).
11−
12−## Normalizes to
13−
14−Default, if the sample is an atom; `p`, if the head of the sample
15−is an atom; `q` otherwise.
16−
17−## Defaults to
18−
19−The default of `p`.
20−
21−## Syntax
22−
23−Regular: *2-fixed*.
24−
25−Product: a structure which applies `p` if its sample is an atom,
26−`q` if its sample is a cell.
27−
28−Regular form: *2-fixed*.
29−
30−Example:
31−
32−```
33−~zod:dojo> =a $@(%foo $:(p=%baz q=@ud))
34−
35−~zod:dojo> (a %foo)
36−%foo
37−
38−~zod:dojo> `a`[%baz 99]
39−[p=%baz q=99]
40−
41−~zod:dojo> $:a
42−[%foo p=0 q=0]
43−```
reference/hoon-expressions/rune/bus/wut.udondeleted−48
@@ -1,48 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'4'
4− title/'$? "buswut"'
5− ==
6−;>
7−
8−# `$? "buswut"`
9−
10−`[%bswt p=(list spec)]`: form a type from a union of other types.
11−
12−## Normalizes to
13−
14−The first item in `p` which normalizes the sample to itself.
15−
16−Void, if `p` is empty.
17−
18−## Defaults to
19−
20−The first item in `p`.
21−
22−## Syntax
23−
24−Regular: *running*.
25−
26−Irregular: `?(%foo %baz)` is `$?(%foo %baz)`.
27−
28−## Discussion
29−
30−For a union of atoms, a `$?` is fine. For more complex nouns,
31−always try to use a [`$%`](../cen/), [`$@`](../vat/) or
32−[`$^`](../ket/), at least if you expect your structure to be used as a
33−normalizer.
34−
35−## Examples
36−
37−```
38−~zod:dojo> =a ?(%foo %baz %baz)
39−
40−~zod:dojo> (a %baz)
41−%baz
42−
43−~zod:dojo> (a [37 45])
44−%baz
45−
46−~zod:dojo> $:a
47−%baz
48−```
reference/hoon-expressions/rune/cen.udon+495−1
@@ -13,4 +13,498 @@ These runes reduce to the `%=` rune
13
13
14## Runes
14## Runes
15
15
16−;list(datapreview "true", classname "runes");
16+;=
17+ ;h3
18+ ;div(id "cencab"): %_ "cencab"
19+ ==
20+==
21+
22+Resolve a wing with changes, preserving type.
23+
24+##### Syntax
25+
26+Regular, tall:
27+
28+```
29+%_ a=wing
30+ b=wing c=hoon
31+ d=wing e=hoon
32+ ...
33+ f=wing g=hoon
34+==
35+```
36+
37+Regular, flat:
38+
39+```
40+%_(a=wing b=wing c=hoon, d=wing e=hoon, ...)
41+```
42+
43+AST:
44+
45+```
46+[%cncb p=wing q=(list (pair wing hoon))]
47+```
48+
49+##### Semantics
50+
51+A `%_` expression resolves to the value of the subject at wing `a`, but modified according to a series of changes: `b` is replaced with the product of `c`, `d` with the product of `e`, and so on. At compile time a type check is performed to ensure that the resulting value is of the same type as `a`.
52+
53+##### Expands to
54+
55+```
56+^+(a %=(a b c, d e, ...))
57+```
58+
59+##### Discussion
60+
61+`%_` is different from `%=` because `%=` can change the type of a wing with mutations. `%_` preserves the wing type.
62+
63+See [how wings are resolved](/docs/reference/hoon-expressions/limb/wing).
64+
65+##### Examples
66+
67+```
68+~zod:dojo> =foo [p=42 q=6]
69+
70+~zod:dojo> foo(p %baz)
71+[p=%baz q=6]
72+
73+~zod:dojo> foo(p [55 99])
74+[p=[55 99] q=6]
75+
76+~zod:dojo> %_(foo p %baz)
77+[p=7.496.034 99]
78+
79+~zod:dojo> %_(foo p [55 99])
80+! nest-fail
81+```
82+
83+;=
84+ ;h3
85+ ;div(id "cencol"): %: "cencol"
86+ ==
87+==
88+
89+Call a gate with many arguments.
90+
91+##### Syntax
92+
93+Regular:
94+
95+```
96+%: a=hoon
97+ b=hoon
98+ c=hoon
99+ ...
100+ d=hoon
101+==
102+```
103+
104+AST:
105+
106+```
107+[%cncl p=hoon q=(list hoon)]
108+```
109+
110+##### Semantics
111+
112+A `%:` expression calls a gate with many arguments. `a` is the gate to be called, and `b` through `d` are the arguments. If there is only one subexpression after `a`, its product is the sample. Otherwise, a single argument is constructed by evaluating all of `b` through `d` -- however many subexpressions there are -- and putting the result in a cell: `[b c ... d]`.
113+
114+##### Discussion
115+
116+When `%:` is used in tall-form syntax, the series of expressions after `p` must be terminated with `==`.
117+
118+##### Examples
119+
120+```
121+> %: add 22 33 ==
122+55
123+
124+> =adder |= a=*
125+ =+ c=0
126+ |-
127+ ?@ a (add a c)
128+ ?^ -.a !!
129+ $(c (add -.a c), a +.a)
130+
131+> %: adder 22 33 44 ==
132+99
133+
134+> %: adder 22 33 44 55 ==
135+154
136+
137+> %:(adder 22 33 44 ~)
138+99
139+```
140+
141+;=
142+ ;h3
143+ ;div(id "cendot"): %. "cendot"
144+ ==
145+==
146+
147+Call a gate (function), inverted.
148+
149+##### Syntax
150+
151+Regular:
152+
153+```
154+%. a=hoon b=hoon
155+```
156+
157+AST:
158+
159+```
160+[%cndt p=hoon q=hoon]
161+```
162+
163+##### Semantics
164+
165+The `%.` rune is for evaluating the `$` arm of a gate, i.e., calling a function. `a` is for the desired sample value (i.e., input value), and `b` is the gate.
166+
167+##### Expands to
168+
169+```
170+%-(b=hoon a=hoon)
171+```
172+
173+##### Discussion
174+
175+`%.` is just like `%-`, but with its subexpressions reversed; the argument comes first, and then the gate.
176+
177+##### Examples
178+
179+```
180+~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
181+
182+~zod:dojo> %.([1 2 3] add-triple)
183+6
184+```
185+
186+;=
187+ ;h3
188+ ;div(id "cenhep"): %- "cenhep"
189+ ==
190+==
191+
192+Call a gate (function).
193+
194+##### Syntax
195+
196+Regular:
197+
198+```
199+%- a=hoon b=hoon
200+```
201+
202+Irregular:
203+
204+```
205+(a=hoon b=hoon)
206+```
207+
208+AST:
209+
210+```
211+[%cnhp p=hoon q=hoon]
212+```
213+
214+##### Semantics
215+
216+This rune is for evaluating the `$` arm of a gate, i.e., calling a gate as a function. `a` is the gate, and `b` is the desired sample value (i.e., input value) for the gate.
217+
218+##### Expands to
219+
220+```
221+%~($ a b)
222+```
223+
224+##### Discussion
225+
226+`%-` is used to call a function; `a` is the function ([`gate`](/docs/reference/hoon-expressions/rune/bar#bartis),
227+`q` the argument. `%-` is a special case of [`%~` ("censig")](#censig), and a gate is a special case of a [door](/docs/reference/hoon-expressions/rune/bar#barcab).
228+
229+##### Examples
230+
231+```
232+~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
233+~zod:dojo> (add-triple 1 2 3)
234+6
235+~zod:dojo> %-(add-triple [1 2 3])
236+6
237+```
238+
239+;=
240+ ;h3
241+ ;div(id "cenket"): %- "cenket"
242+ ==
243+==
244+
245+Call gate with triple sample.
246+
247+##### Syntax
248+
249+Regular:
250+
251+```
252+%^ a=hoon b=hoon c=hoon d=hoon
253+```
254+
255+AST:
256+
257+```
258+[%cnkt p=hoon q=hoon r=hoon s=hoon]
259+```
260+
261+
262+##### Expands to
263+
264+```
265+%-(a=hoon [b=hoon c=hoon d=hoon])
266+```
267+
268+##### Examples
269+
270+```
271+~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
272+
273+~zod:dojo> %^(add-triple 1 2 3)
274+6
275+```
276+
277+;=
278+ ;h3
279+ ;div(id "cenlus"): %+ "cenlus"
280+ ==
281+==
282+
283+Call gate with a cell sample.
284+
285+##### Syntax
286+
287+Regular:
288+
289+```
290+%+ a=hoon b=hoon c=hoon
291+```
292+
293+AST:
294+
295+```
296+[%cnls p=hoon q=hoon r=hoon]
297+```
298+
299+##### Semantics
300+
301+A `%+` expression is for calling a gate with a cell sample. `a` is the gate to be called, `b` is for the head of the sample, and `c` is for the sample tail.
302+
303+##### Expands to
304+
305+```
306+%-(a=hoon [b=hoon c=hoon])
307+```
308+
309+##### Examples
310+
311+```
312+~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
313+
314+~zod:dojo> %+(add-triple 1 [2 3])
315+6
316+```
317+
318+;=
319+ ;h3
320+ ;div(id "censig"): %~ "censig"
321+ ==
322+==
323+
324+Evaluate an arm in a door.
325+
326+##### Syntax
327+
328+Regular:
329+
330+```
331+%~ a=wing b=hoon
332+ c=hoon
333+ d=hoon
334+ ...
335+ e=hoon
336+==
337+```
338+
339+Irregular:
340+
341+`~(a b c)` is `%~(a b c)`.
342+`~(a b c d e)` is `%~(a b [c d e])`.
343+
344+AST:
345+
346+```
347+[%cnsg p=wing q=hoon r=(list hoon)]
348+```
349+
350+##### Semantics
351+
352+A `%~` expression evaluates the arm of a door (i.e., a core with a sample). `a` is a wing that resolves to the arm from within the door in question. `b` is the door itself. If there is only one subexpression after `b`, `c`, then the product of `c` becomes the door's sample value. If there are multiple subexpressions after `b`, their products are made into a cell, `[c d ... e]`, and that becomes the door's sample value.
353+
354+##### Discussion
355+
356+`%~` is the general case of a function call, `%-`. In both, we replace the sample (`+6`) of a core. In `%-` the core is a gate and the `$` arm is evaluated. In `%~` the core is a door and any arm may be evaluated. You must identify the arm to be run: `%~(arm door arg)`.
357+
358+See also [`|_`](/docs/reference/hoon-expressions/rune/bar#barcab).
359+
360+##### Examples
361+
362+```
363+> =mycore |_ a=@
364+ ++ plus-two (add 2 a)
365+ ++ double (mul 2 a)
366+ --
367+> ~(plus-two mycore 10)
368+12
369+
370+> ~(double mycore 10)
371+20
372+```
373+
374+;=
375+ ;h3
376+ ;div(id "centar"): %* "centar"
377+ ==
378+==
379+
380+Evaluate an expression, then resolve a wing with changes.
381+
382+##### Syntax
383+
384+Regular:
385+
386+```
387+%* a=wing b=hoon
388+ c=wing d=hoon
389+ e=wing f=hoon
390+ ...
391+ g=wing h=hoon
392+==
393+```
394+
395+AST:
396+
397+```
398+[%cntr p=wing q=hoon r=(list (pair wing hoon))]
399+```
400+
401+##### Semantics
402+
403+A `%*` expression evaluates some arbitrary Hoon expression, `b`, and then resolves a wing of of that result, with changes. `a` is the wing to be resolved, and one or more changes is defined by the subexpressions after `b`.
404+
405+##### Expands to
406+
407+```
408+=+ b=hoon
409+%= a=wing
410+ c=wing d=hoon
411+ e=wing f=hoon
412+ ...
413+ g=wing h=hoon
414+==
415+```
416+
417+##### Examples
418+
419+```
420+> %*($ add a 2, b 3)
421+5
422+
423+> %*(b [a=[12 14] b=[c=12 d=44]] c 11)
424+[c=11 d=44]
425+
426+> %*(b [a=[12 14] b=[c=12 d=44]] c 11, d 33)
427+[c=11 d=33]
428+
429+> =foo [a=1 b=2 c=3 d=4]
430+
431+> %*(+ foo c %hello, d %world)
432+[b=2 c=%hello d=%world]
433+
434+> =+(foo=[a=1 b=2 c=3] foo(b 7, c 10))
435+[a=1 b=7 c=10]
436+
437+> %*(foo [foo=[a=1 b=2 c=3]] b 7, c 10)
438+[a=1 b=7 c=10]
439+```
440+
441+;=
442+ ;h3
443+ ;div(id "centis"): %= "centis"
444+ ==
445+==
446+
447+Resolve a wing with changes.
448+
449+##### Syntax
450+
451+Regular:
452+
453+```
454+%= a=wing
455+ b=wing c=hoon
456+ d=wing e=hoon
457+ ...
458+ f=wing g=hoon
459+==
460+```
461+
462+Irregular:
463+
464+`foo(x 1, y 2, z 3)` is `%=(foo x 1, y 2, z 3)`.
465+
466+AST:
467+
468+```
469+[%cnts p=wing q=(list (pair wing hoon))]
470+```
471+
472+##### Semantics
473+
474+A `%=` expression resolves a wing of the subject, but with changes made.
475+
476+If `a` resolves to a leg, a series of changes are made to wings of that leg (`b`, `d`, and `f` above are replaced with the respective products of `c`, `e`, and `g` above). The modified leg is returned.
477+
478+If `a` resolves to an arm, a series of changes are made to wings of the parent core of that arm. (Again, `b`, `d`, and `f` are replaced with the respective products of `c`, `e`, and `g`.) The arm is computed with the modified core as the subject, and the product is returned.
479+
480+##### Discussion
481+
482+Note that `a` is a wing, not just any expression. Knowing that a function
483+call `(foo baz)` involves evaluating `foo`, replacing its sample
484+at slot `+6` with `baz`, and then resolving to the `$` limb, you might think
485+`(foo baz)` would mean `%=(foo +6 baz)`.
486+
487+But it's actually `=+(foo =>(%=(+2 +6 baz) $))`. Even if `foo` is
488+a wing, we would just be mutating `+6` within the core that defines the
489+`foo` arm. Instead we want to modify the *product* of `foo` -- the gate
490+-- so we have to pin it into the subject.
491+
492+Here's that again in tall form:
493+
494+```
495+=+ foo
496+=> %= +2
497+ +6 baz
498+ ==
499+ $
500+```
501+
502+##### Examples
503+
504+```
505+~zod:dojo> =foo [p=5 q=6]
506+~zod:dojo> foo(p 42)
507+[p=42 q=6]
508+~zod:dojo> foo(+3 99)
509+[p=5 99]
510+```
reference/hoon-expressions/rune/cen/cab.udondeleted−69
@@ -1,69 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'8'
4− title/'%_ "cencab"'
5− ==
6−;>
7−
8−# `%_ "cencab"`
9−
10−Resolve a wing with changes, preserving type.
11−
12−## Syntax
13−
14−Regular, tall:
15−
16−```
17−%_ a=wing
18− b=wing c=hoon
19− d=wing e=hoon
20− ...
21− f=wing g=hoon
22−==
23−```
24−
25−Regular, flat:
26−
27−```
28−%_(a=wing b=wing c=hoon, d=wing e=hoon, ...)
29−```
30−
31−AST:
32−
33−```
34−[%cncb p=wing q=(list (pair wing hoon))]
35−```
36−
37−## Semantics
38−
39−A `%_` expression resolves to the value of the subject at wing `a`, but modified according to a series of changes: `b` is replaced with the product of `c`, `d` with the product of `e`, and so on. At compile time a type check is performed to ensure that the resulting value is of the same type as `a`.
40−
41−## Expands to
42−
43−```
44−^+(a %=(a b c, d e, ...))
45−```
46−
47−## Discussion
48−
49−`%_` is different from `%=` because `%=` can change the type of a wing with mutations. `%_` preserves the wing type.
50−
51−See [how wings are resolved](../../limb/wing).
52−
53−## Examples
54−
55−```
56−~zod:dojo> =foo [p=42 q=6]
57−
58−~zod:dojo> foo(p %baz)
59−[p=%baz q=6]
60−
61−~zod:dojo> foo(p [55 99])
62−[p=[55 99] q=6]
63−
64−~zod:dojo> %_(foo p %baz)
65−[p=7.496.034 99]
66−
67−~zod:dojo> %_(foo p [55 99])
68−! nest-fail
69−```
reference/hoon-expressions/rune/cen/col.udondeleted−60
@@ -1,60 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'9'
4− title/'%: "cencol"'
5− ==
6−;>
7−
8−# `%: "cencol"`
9−
10−Call a gate with many arguments.
11−
12−## Syntax
13−
14−Regular:
15−
16−```
17−%: a=hoon
18− b=hoon
19− c=hoon
20− ...
21− d=hoon
22−==
23−```
24−
25−AST:
26−
27−```
28−[%cncl p=hoon q=(list hoon)]
29−```
30−
31−## Semantics
32−
33−A `%:` expression calls a gate with many arguments. `a` is the gate to be called, and `b` through `d` are the arguments. If there is only one subexpression after `a`, its product is the sample. Otherwise, a single argument is constructed by evaluating all of `b` through `d` -- however many subexpressions there are -- and putting the result in a cell: `[b c ... d]`.
34−
35−## Discussion
36−
37−When `%:` is used in tall-form syntax, the series of expressions after `p` must be terminated with `==`.
38−
39−## Examples
40−
41−```
42−> %: add 22 33 ==
43−55
44−
45−> =adder |= a=*
46− =+ c=0
47− |-
48− ?@ a (add a c)
49− ?^ -.a !!
50− $(c (add -.a c), a +.a)
51−
52−> %: adder 22 33 44 ==
53−99
54−
55−> %: adder 22 33 44 55 ==
56−154
57−
58−> %:(adder 22 33 44 ~)
59−99
60−```
reference/hoon-expressions/rune/cen/dot.udondeleted−47
@@ -1,47 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'3'
4− title/'%. "cendot"'
5− ==
6−;>
7−
8−# `%. "cendot"`
9−
10−Call a gate (function), inverted.
11−
12−## Syntax
13−
14−Regular:
15−
16−```
17−%. a=hoon b=hoon
18−```
19−
20−AST:
21−
22−```
23−[%cndt p=hoon q=hoon]
24−```
25−
26−## Semantics
27−
28−The `%.` rune is for evaluating the `$` arm of a gate, i.e., calling a function. `a` is for the desired sample value (i.e., input value), and `b` is the gate.
29−
30−## Expands to
31−
32−```
33−%-(b=hoon a=hoon)
34−```
35−
36−## Discussion
37−
38−`%.` is just like `%-`, but with its subexpressions reversed; the argument comes first, and then the gate.
39−
40−## Examples
41−
42−```
43−~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
44−
45−~zod:dojo> %.([1 2 3] add-triple)
46−6
47−```
reference/hoon-expressions/rune/cen/hep.udondeleted−55
@@ -1,55 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'2'
4− title/'%- "cenhep"'
5− ==
6−;>
7−
8−# `%- "cenhep"`
9−
10−Call a gate (function).
11−
12−## Syntax
13−
14−Regular:
15−
16−```
17−%- a=hoon b=hoon
18−```
19−
20−Irregular:
21−
22−```
23−(a=hoon b=hoon)
24−```
25−
26−AST:
27−
28−```
29−[%cnhp p=hoon q=hoon]
30−```
31−
32−## Semantics
33−
34−This rune is for evaluating the `$` arm of a gate, i.e., calling a gate as a function. `a` is the gate, and `b` is the desired sample value (i.e., input value) for the gate.
35−
36−## Expands to
37−
38−```
39−%~($ a b)
40−```
41−
42−## Discussion
43−
44−`%-` is used to call a function; `a` is the function ([`gate`](../../bar/tis),
45−`q` the argument. `%-` is a special case of [`%~` ("censig")](../sig), and a gate is a special case of a [door](../../bar/cab).
46−
47−## Examples
48−
49−```
50−~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
51−~zod:dojo> (add-triple 1 2 3)
52−6
53−~zod:dojo> %-(add-triple [1 2 3])
54−6
55−```
reference/hoon-expressions/rune/cen/ket.udondeleted−41
@@ -1,41 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'5'
4− title/'%^ "cenket"'
5− ==
6−;>
7−
8−# `%^ "cenket"`
9−
10−Call gate with triple sample.
11−
12−## Syntax
13−
14−Regular:
15−
16−```
17−%^ a=hoon b=hoon c=hoon d=hoon
18−```
19−
20−AST:
21−
22−```
23−[%cnkt p=hoon q=hoon r=hoon s=hoon]
24−```
25−
26−##
27−
28−## Expands to
29−
30−```
31−%-(a=hoon [b=hoon c=hoon d=hoon])
32−```
33−
34−## Examples
35−
36−```
37−~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
38−
39−~zod:dojo> %^(add-triple 1 2 3)
40−6
41−```
reference/hoon-expressions/rune/cen/lus.udondeleted−43
@@ -1,43 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'4'
4− title/'%+ "cenlus"'
5− ==
6−;>
7−
8−# `%+ "cenlus"`
9−
10−Call gate with a cell sample.
11−
12−## Syntax
13−
14−Regular:
15−
16−```
17−%+ a=hoon b=hoon c=hoon
18−```
19−
20−AST:
21−
22−```
23−[%cnls p=hoon q=hoon r=hoon]
24−```
25−
26−## Semantics
27−
28−A `%+` expression is for calling a gate with a cell sample. `a` is the gate to be called, `b` is for the head of the sample, and `c` is for the sample tail.
29−
30−## Expands to
31−
32−```
33−%-(a=hoon [b=hoon c=hoon])
34−```
35−
36−## Examples
37−
38−```
39−~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
40−
41−~zod:dojo> %+(add-triple 1 [2 3])
42−6
43−```
reference/hoon-expressions/rune/cen/sig.udondeleted−58
@@ -1,58 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'6'
4− title/'%~ "censig"'
5− ==
6−;>
7−
8−# `%~ "censig"`
9−
10−Evaluate an arm in a door.
11−
12−## Syntax
13−
14−Regular:
15−
16−```
17−%~ a=wing b=hoon
18− c=hoon
19− d=hoon
20− ...
21− e=hoon
22−==
23−```
24−
25−Irregular:
26−
27−`~(a b c)` is `%~(a b c)`.
28−`~(a b c d e)` is `%~(a b [c d e])`.
29−
30−AST:
31−
32−```
33−[%cnsg p=wing q=hoon r=(list hoon)]
34−```
35−
36−## Semantics
37−
38−A `%~` expression evaluates the arm of a door (i.e., a core with a sample). `a` is a wing that resolves to the arm from within the door in question. `b` is the door itself. If there is only one subexpression after `b`, `c`, then the product of `c` becomes the door's sample value. If there are multiple subexpressions after `b`, their products are made into a cell, `[c d ... e]`, and that becomes the door's sample value.
39−
40−## Discussion
41−
42−`%~` is the general case of a function call, `%-`. In both, we replace the sample (`+6`) of a core. In `%-` the core is a gate and the `$` arm is evaluated. In `%~` the core is a door and any arm may be evaluated. You must identify the arm to be run: `%~(arm door arg)`.
43−
44−See also [`|_`](../../bar/cab).
45−
46−## Examples
47−
48−```
49−> =mycore |_ a=@
50− ++ plus-two (add 2 a)
51− ++ double (mul 2 a)
52− --
53−> ~(plus-two mycore 10)
54−12
55−
56−> ~(double mycore 10)
57−20
58−```
reference/hoon-expressions/rune/cen/tar.udondeleted−69
@@ -1,69 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'7'
4− title/'%* "centar"'
5− ==
6−;>
7−
8−# `%* "centar"`
9−
10−Evaluate an expression, then resolve a wing with changes.
11−
12−## Syntax
13−
14−Regular:
15−
16−```
17−%* a=wing b=hoon
18− c=wing d=hoon
19− e=wing f=hoon
20− ...
21− g=wing h=hoon
22−==
23−```
24−
25−AST:
26−
27−```
28−[%cntr p=wing q=hoon r=(list (pair wing hoon))]
29−```
30−
31−## Semantics
32−
33−A `%*` expression evaluates some arbitrary Hoon expression, `b`, and then resolves a wing of of that result, with changes. `a` is the wing to be resolved, and one or more changes is defined by the subexpressions after `b`.
34−
35−## Expands to
36−
37−```
38−=+ b=hoon
39−%= a=wing
40− c=wing d=hoon
41− e=wing f=hoon
42− ...
43− g=wing h=hoon
44−==
45−```
46−
47−## Examples
48−
49−```
50−> %*($ add a 2, b 3)
51−5
52−
53−> %*(b [a=[12 14] b=[c=12 d=44]] c 11)
54−[c=11 d=44]
55−
56−> %*(b [a=[12 14] b=[c=12 d=44]] c 11, d 33)
57−[c=11 d=33]
58−
59−> =foo [a=1 b=2 c=3 d=4]
60−
61−> %*(+ foo c %hello, d %world)
62−[b=2 c=%hello d=%world]
63−
64−> =+(foo=[a=1 b=2 c=3] foo(b 7, c 10))
65−[a=1 b=7 c=10]
66−
67−> %*(foo [foo=[a=1 b=2 c=3]] b 7, c 10)
68−[a=1 b=7 c=10]
69−```
reference/hoon-expressions/rune/cen/tis.udondeleted−73
@@ -1,73 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'1'
4− title/'%= "centis"'
5− ==
6−;>
7−
8−# `%= "centis"`
9−
10−Resolve a wing with changes.
11−
12−## Syntax
13−
14−Regular:
15−
16−```
17−%= a=wing
18− b=wing c=hoon
19− d=wing e=hoon
20− ...
21− f=wing g=hoon
22−==
23−```
24−
25−Irregular:
26−
27−`foo(x 1, y 2, z 3)` is `%=(foo x 1, y 2, z 3)`.
28−
29−AST:
30−
31−```
32−[%cnts p=wing q=(list (pair wing hoon))]
33−```
34−
35−## Semantics
36−
37−A `%=` expression resolves a wing of the subject, but with changes made.
38−
39−If `a` resolves to a leg, a series of changes are made to wings of that leg (`b`, `d`, and `f` above are replaced with the respective products of `c`, `e`, and `g` above). The modified leg is returned.
40−
41−If `a` resolves to an arm, a series of changes are made to wings of the parent core of that arm. (Again, `b`, `d`, and `f` are replaced with the respective products of `c`, `e`, and `g`.) The arm is computed with the modified core as the subject, and the product is returned.
42−
43−## Discussion
44−
45−Note that `a` is a wing, not just any expression. Knowing that a function
46−call `(foo baz)` involves evaluating `foo`, replacing its sample
47−at slot `+6` with `baz`, and then resolving to the `$` limb, you might think
48−`(foo baz)` would mean `%=(foo +6 baz)`.
49−
50−But it's actually `=+(foo =>(%=(+2 +6 baz) $))`. Even if `foo` is
51−a wing, we would just be mutating `+6` within the core that defines the
52−`foo` arm. Instead we want to modify the *product* of `foo` -- the gate
53−-- so we have to pin it into the subject.
54−
55−Here's that again in tall form:
56−
57−```
58−=+ foo
59−=> %= +2
60− +6 baz
61− ==
62− $
63−```
64−
65−## Examples
66−
67−```
68−~zod:dojo> =foo [p=5 q=6]
69−~zod:dojo> foo(p 42)
70−[p=42 q=6]
71−~zod:dojo> foo(+3 99)
72−[p=5 99]
73−```
reference/hoon-expressions/rune/col.udon+263−1
@@ -11,4 +11,266 @@ The `:` ("col") expressions are used to produce cells, which are pairs of values
11
11
12## Runes
12## Runes
13
13
14−;list(datapreview "true", classname "runes");
14+;=
15+ ;h3
16+ ;div(id "colcab"): :_ "colcab"
17+ ==
18+==
19+
20+`[%clcb p=hoon q=hoon]`; construct a cell, inverted.
21+
22+##### Expands to
23+
24+```
25+:-(q p)
26+```
27+
28+##### Syntax
29+
30+Regular: *2-fixed*.
31+
32+##### Examples
33+
34+```
35+~zod:dojo> :_(1 2)
36+[2 1]
37+```
38+
39+;=
40+ ;h3
41+ ;div(id "colcol"): :: "colcol"
42+ ==
43+==
44+
45+Code comment
46+
47+##### Syntax
48+
49+:: any text you like!
50+
51+##### Examples
52+
53+```
54+::
55+:: this is commented code
56+::
57+|= a=@ :: a gate
58+(add 2 a) :: that adds 2
59+ :: to the input
60+```
61+
62+;=
63+ ;h3
64+ ;div(id "colhep"): :- "colhep"
65+ ==
66+==
67+
68+`[%clhp p=hoon q=hoon]`: construct a cell (2-tuple).
69+
70+##### Produces
71+
72+The cell of `p` and `q`.
73+
74+##### Syntax
75+
76+Regular: *2-fixed*.
77+
78+Irregular: `[a b]` is `:-(a b)`.
79+
80+Irregular: `[a b c]` is `[a [b c]]`.
81+
82+Irregular: `a^b^c` is `[a b c]`.
83+
84+Irregular: `a/b` is `[%a b]`.
85+
86+Irregular: `` `a `` is `[~ a]`.
87+
88+Irregular: `~[a b]` is `[a b ~]`.
89+
90+Irregular: `[a b c]~` is `[[a b c] ~]`.
91+
92+## Discussion
93+
94+Hoon expressions actually use the same "autocons" pattern as Nock
95+formulas. If you're assembling expressions (which usually only the
96+compiler does), `[a b]` is the same as `:-(a b)`.
97+
98+##### Examples
99+
100+```
101+~zod:dojo> :-(1 2)
102+[1 2
103+
104+~zod:dojo> 1^2
105+[1 2]
106+
107+~zod:dojo> 1/2
108+[%1 2]
109+
110+~zod:dojo> `1
111+[~ 1]
112+```
113+
114+;=
115+ ;h3
116+ ;div(id "colket"): :^ "colket"
117+ ==
118+==
119+
120+`[%clkt p=hoon q=hoon r=hoon s=hoon]`: construct a quadruple (4-tuple).
121+
122+##### Expands to
123+
124+```
125+:-(p :-(q :-(r s)))
126+```
127+
128+##### Syntax
129+
130+Regular: *4-fixed*.
131+
132+##### Examples
133+
134+```
135+~zod:dojo> :^(1 2 3 4)
136+[1 2 3 4]
137+
138+~zod:dojo> :^ 5
139+ 6
140+ 7
141+ 8
142+[5 6 7 8]
143+```
144+
145+;=
146+ ;h3
147+ ;div(id "collus"): :+ "collus"
148+ ==
149+==
150+
151+
152+`[%clls p=hoon q=hoon r=hoon]`: construct a triple (3-tuple).
153+
154+##### Expands to:
155+
156+```
157+:-(p :-(q r))
158+```
159+
160+##### Syntax
161+
162+Regular: *3-fixed*.
163+
164+##### Examples
165+
166+```
167+/~zod:dojo> :+ 1
168+ 2
169+ 3
170+[1 2 3]
171+
172+~zod:dojo> :+(%a ~ 'b')
173+[%a ~ 'b']
174+```
175+
176+;=
177+ ;h3
178+ ;div(id "cosig"): :~ "colsig"
179+ ==
180+==
181+
182+`[%clsg p=(list hoon)]`: construct a null-terminated list.
183+
184+##### Expands to
185+
186+*Pseudocode*: `a`, `b`, `c`, ... as elements of `p`:
187+
188+```
189+:-(a :-(b :-(c :-(... :-(z ~)))))
190+```
191+
192+##### Compiler Macro
193+
194+```
195+|-
196+?~ p
197+ ~
198+:- i.p
199+$(p t.p)
200+```
201+
202+##### Syntax
203+
204+Regular: *running*.
205+
206+##### Examples
207+
208+```
209+~zod:dojo> :~(5 3 4 2 1)
210+[5 3 4 2 1 ~]
211+
212+~zod:dojo> ~[5 3 4 2 1]
213+[5 3 4 2 1 ~]
214+
215+~zod:dojo> :~ 5
216+ 3
217+ 4
218+ 2
219+ 1
220+ ==
221+[5 3 4 2 1 ~]
222+```
223+
224+;=
225+ ;h3
226+ ;div(id "coltar"): :* "coltar"
227+ ==
228+==
229+
230+`[%cltr p=(list hoon)]`: construct an n-tuple.
231+
232+##### Expands to
233+
234+*Pseudocode*: `a`, `b`, `c`, ... as elements of `p`:
235+
236+```
237+:-(a :-(b :-(c :-(... z)))))
238+```
239+
240+##### Compiler Macro
241+
242+```
243+|-
244+?~ p
245+ !!
246+?~ t.p
247+ i.p
248+:- i.p
249+$(p t.p)
250+```
251+
252+##### Syntax
253+
254+Regular: *running*.
255+
256+##### Examples
257+
258+```
259+~zod:dojo> :*(5 3 4 1 4 9 0 ~ 'a')
260+[5 3 4 1 4 9 0 ~ 'a']
261+
262+~zod:dojo> [5 3 4 1 4 9 0 ~ 'a']
263+[5 3 4 1 4 9 0 ~ 'a']
264+
265+~zod:dojo> :* 5
266+ 3
267+ 4
268+ 1
269+ 4
270+ 9
271+ 0
272+ ~
273+ 'a'
274+ ==
275+[5 3 4 1 4 9 0 ~ 'a']
276+```
reference/hoon-expressions/rune/col/cab.udondeleted−27
@@ -1,27 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'2'
4− title/':_ "colcab"'
5− ==
6−;>
7−
8−# `:_ "colcab"`
9−
10−`[%clcb p=hoon q=hoon]`; construct a cell, inverted.
11−
12−### Expands to
13−
14−```
15−:-(q p)
16−```
17−
18−### Syntax
19−
20−Regular: *2-fixed*.
21−
22−### Examples
23−
24−```
25−~zod:dojo> :_(1 2)
26−[2 1]
27−```
reference/hoon-expressions/rune/col/col.udondeleted−25
@@ -1,25 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'7'
4− title/':: "colcol"'
5− ==
6−;>
7−
8−# `:: "colcol"`
9−
10−Code comment
11−
12−### Syntax
13−
14−:: any text you like!
15−
16−### Examples
17−
18−```
19−::
20−:: this is commented code
21−::
22−|= a=@ :: a gate
23−(add 2 a) :: that adds 2
24− :: to the input
25−```
reference/hoon-expressions/rune/col/hep.udondeleted−54
@@ -1,54 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'1'
4− title/':- "colhep"'
5− ==
6−;>
7−
8−# `:- "colhep"`
9−
10−`[%clhp p=hoon q=hoon]`: construct a cell (2-tuple).
11−
12−## Produces
13−
14−The cell of `p` and `q`.
15−
16−## Syntax
17−
18−Regular: *2-fixed*.
19−
20−Irregular: `[a b]` is `:-(a b)`.
21−
22−Irregular: `[a b c]` is `[a [b c]]`.
23−
24−Irregular: `a^b^c` is `[a b c]`.
25−
26−Irregular: `a/b` is `[%a b]`.
27−
28−Irregular: `` `a `` is `[~ a]`.
29−
30−Irregular: `~[a b]` is `[a b ~]`.
31−
32−Irregular: `[a b c]~` is `[[a b c] ~]`.
33−
34−## Discussion
35−
36−Hoon expressions actually use the same "autocons" pattern as Nock
37−formulas. If you're assembling expressions (which usually only the
38−compiler does), `[a b]` is the same as `:-(a b)`.
39−
40−## Examples
41−
42−```
43−~zod:dojo> :-(1 2)
44−[1 2
45−
46−~zod:dojo> 1^2
47−[1 2]
48−
49−~zod:dojo> 1/2
50−[%1 2]
51−
52−~zod:dojo> `1
53−[~ 1]
54−```
reference/hoon-expressions/rune/col/ket.udondeleted−33
@@ -1,33 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'4'
4− title/':^ "colket"'
5− ==
6−;>
7−
8−# `:^ "colket"`
9−
10−`[%clkt p=hoon q=hoon r=hoon s=hoon]`: construct a quadruple (4-tuple).
11−
12−## Expands to
13−
14−```
15−:-(p :-(q :-(r s)))
16−```
17−
18−## Syntax
19−
20−Regular: *4-fixed*.
21−
22−## Examples
23−
24−```
25−~zod:dojo> :^(1 2 3 4)
26−[1 2 3 4]
27−
28−~zod:dojo> :^ 5
29− 6
30− 7
31− 8
32−[5 6 7 8]
33−```
reference/hoon-expressions/rune/col/lus.udondeleted−32
@@ -1,32 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'3'
4− title/':+ "collus"'
5− ==
6−;>
7−
8−# `:+ "collus"`
9−
10−`[%clls p=hoon q=hoon r=hoon]`: construct a triple (3-tuple).
11−
12−## Expands to:
13−
14−```
15−:-(p :-(q r))
16−```
17−
18−## Syntax
19−
20−Regular: *3-fixed*.
21−
22−## Examples
23−
24−```
25−/~zod:dojo> :+ 1
26− 2
27− 3
28−[1 2 3]
29−
30−~zod:dojo> :+(%a ~ 'b')
31−[%a ~ 'b']
32−```
reference/hoon-expressions/rune/col/sig.udondeleted−50
@@ -1,50 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'6'
4− title/':~ "colsig"'
5− ==
6−;>
7−
8−# `:~ "colsig"`
9−
10−`[%clsg p=(list hoon)]`: construct a null-terminated list.
11−
12−## Expands to
13−
14−*Pseudocode*: `a`, `b`, `c`, ... as elements of `p`:
15−
16−```
17−:-(a :-(b :-(c :-(... :-(z ~)))))
18−```
19−
20−### Compiler macro
21−
22−```
23−|-
24−?~ p
25− ~
26−:- i.p
27−$(p t.p)
28−```
29−
30−## Syntax
31−
32−Regular: *running*.
33−
34−## Examples
35−
36−```
37−~zod:dojo> :~(5 3 4 2 1)
38−[5 3 4 2 1 ~]
39−
40−~zod:dojo> ~[5 3 4 2 1]
41−[5 3 4 2 1 ~]
42−
43−~zod:dojo> :~ 5
44− 3
45− 4
46− 2
47− 1
48− ==
49−[5 3 4 2 1 ~]
50−```
reference/hoon-expressions/rune/col/tar.udondeleted−56
@@ -1,56 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'5'
4− title/':* "coltar"'
5− ==
6−;>
7−
8−# `:* "coltar"`
9−
10−`[%cltr p=(list hoon)]`: construct an n-tuple.
11−
12−## Expands to
13−
14−*Pseudocode*: `a`, `b`, `c`, ... as elements of `p`:
15−
16−```
17−:-(a :-(b :-(c :-(... z)))))
18−```
19−
20−### Compiler macro
21−
22−```
23−|-
24−?~ p
25− !!
26−?~ t.p
27− i.p
28−:- i.p
29−$(p t.p)
30−```
31−
32−## Syntax
33−
34−Regular: *running*.
35−
36−## Examples
37−
38−```
39−~zod:dojo> :*(5 3 4 1 4 9 0 ~ 'a')
40−[5 3 4 1 4 9 0 ~ 'a']
41−
42−~zod:dojo> [5 3 4 1 4 9 0 ~ 'a']
43−[5 3 4 1 4 9 0 ~ 'a']
44−
45−~zod:dojo> :* 5
46− 3
47− 4
48− 1
49− 4
50− 9
51− 0
52− ~
53− 'a'
54− ==
55−[5 3 4 1 4 9 0 ~ 'a']
56−```
reference/hoon-expressions/rune/constants.udon+197−1
@@ -13,4 +13,200 @@ se, because they have interpolations.)
13
13
14## Expressions
14## Expressions
15
15
16−;list(datapreview "true", classname "runes");
16+;=
17+ ;h3
18+ ;div(id "cold"): `:_ "Cold Atom"`
19+ ==
20+==
21+
22+`[%rock p=term q=@]`; a constant, cold atom.
23+
24+A cold atom is one whose type is inferred to be of a single atom constant.
25+
26+##### Produces
27+
28+A cold (fixed) atom `q` with aura `p`.
29+
30+##### Syntax
31+
32+Irregular: any [warm atom](#warm) form, prefixed with `%`.
33+
34+Irregular: e.g., `%hi`. Character constraints: `a-z`
35+lowercase to start, `a-z` or `0-9` thereafter, with infix
36+hyphens (`hep`), "kebab-case."
37+
38+Irregular: `~`.
39+
40+##### Examples
41+
42+We can see the contrast with warm atoms by using the compiler parser function, `ream`:
43+
44+```
45+> (ream '%hi')
46+[%rock p=%tas q=26.984]
47+
48+> (ream '\'hi\'')
49+[%sand p=%t q=26.984]
50+
51+> (ream '%12')
52+[%rock p=%ud q=12]
53+```
54+
55+;=
56+ ;h3
57+ ;div(id "paths"): `:_ "Paths"`
58+ ==
59+==
60+
61+`[%path p=(list (each @ta hoon))]`: path with interpolation.
62+
63+##### Produces
64+
65+A null-terminated list of the items in `p`, which are either constant
66+`@ta` atoms (`knots`), or expressions producing a `knot`.
67+
68+##### Syntax
69+
70+Irregular: `/this/is/a/path`.
71+
72+##### Examples
73+
74+```
75+> `path`/this/is/a/path
76+/this/is/a/path
77+
78+> `path`/this/is/[`@ta`(cat 3 %a- %test)]/path
79+/this/is/a-test/path
80+
81+> `path`/this/is/(scot %tas 'test')/path
82+/this/is/test/path
83+
84+> /
85+~
86+```
87+
88+;=
89+ ;h3
90+ ;div(id "strings"): `:_ "Strings with Interpolation"`
91+ ==
92+==
93+
94+`[%knit p=(list (each @t hoon))]`: text string with interpolation.
95+
96+##### Produces
97+
98+A tape.
99+
100+##### Syntax
101+
102+Irregular: `"abcdefg"`.
103+
104+Irregular: `"abc{(weld "lmnop" "xyz")}defg"`.
105+
106+```
107+> "abcdefg"
108+"abcdefg"
109+
110+> "abc{(weld "lmnop" "xyz")}defg"
111+"abclmnopxyzdefg"
112+
113+> (ream '"abcdefg"')
114+[%knit p=~[97 98 99 100 101 102 103]]
115+```
116+
117+##### Examples
118+
119+String:
120+
121+```
122+> "hello, world."
123+"hello, world."
124+```
125+
126+String with interpolation:
127+
128+```
129+> =+(planet="world" "hello, {planet}.")
130+"hello, world."
131+```
132+
133+String with interpolated prettyprinting:
134+
135+```
136+> =+(planet=%world "hello, {<planet>}.")
137+"hello, %world."
138+```
139+
140+;=
141+ ;h3
142+ ;div(id "warm"): `:_ "Warm Atoms"`
143+ ==
144+==
145+
146+`[%sand p=term q=@]`; a constant, warm atom.
147+
148+A 'warm' atom is one whose type is inferred to be general, i.e., not just a single atom type.
149+
150+```
151+> `@`12
152+12
153+
154+> `%12`12
155+nest-fail
156+```
157+
158+##### Produces
159+
160+A warm (variable) atom `q` with aura `p`. Use the Hoon compiler parser function `ream` to take a closer look:
161+
162+```
163+> (ream '12')
164+[%sand p=%ud q=12]
165+
166+> (ream '\'Hello!\'')
167+[%sand p=%t q=36.762.444.129.608]
168+```
169+
170+##### Syntax by example
171+
172+Irregular. A table of examples:
173+
174+```
175+@c UTF-32 ~-foobar
176+@da 128-bit absolute date ~2016.4.23..20.09.26..f27b..dead..beef..babe
177+ ~2016.4.23
178+@dr 128-bit relative date ~s17 (17 seconds)
179+ ~m20 (20 minutes)
180+ ~d42 (42 days)
181+@f loobean & (0, yes)
182+ | (1, no)
183+@p ~zod (0)
184+@rd 64-bit IEEE float .~3.14 (pi)
185+ .~-3.14 (negative pi)
186+@rs 32-bit IEEE float .3.14 (pi)
187+ .-3.14 (negative pi)
188+@rq 128-bit IEEE float .~~~3.14 (pi)
189+@rh 16-bit IEEE float .~~3.14 (pi)
190+@sb signed binary --0b10 (2)
191+ -0b101 (-5)
192+@sd signed decimal --2 (2)
193+ -5 (-5)
194+@sv signed base32 --0v68 (200)
195+ -0vfk (-500)
196+@sw signed base64 --0w38 (200)
197+ -0w7Q (500)
198+@sx signed hexadecimal --0x2 (2)
199+ -0x5 -5
200+@t UTF-8 text (cord) 'foobar'
201+@ta ASCII text (knot) ~.foobar
202+@ub unsigned binary 0b10 (2)
203+@uc bitcoin address 0c1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
204+@ud unsigned decimal 42 (42)
205+ 1.420 (1420)
206+@uv unsigned base32 0v3ic5h.6urr6
207+@uw unsigned base64 0wsC5.yrSZC
208+@ux unsigned hexadecimal 0xcafe.babe
209+```
210+
211+The `@uv` characters are `0-9`, `a-v`. The `@uw` characters are
212+`0-9`, `a-z`, `A-Z`, `-` and `~`.
reference/hoon-expressions/rune/constants/cold.udondeleted−41
@@ -1,41 +0,0 @@
1−:- :~ navhome/'/docs/'
2− navuptwo/'true'
3− sort/'2'
4− title/'Cold Atoms'
5− ==
6−;>
7−
8−# Cold Atoms
9−
10−`[%rock p=term q=@]`; a constant, cold atom.
11−
12−A cold atom is one whose type is inferred to be of a single atom constant.
13−
14−### Produces
15−
16−A cold (fixed) atom `q` with aura `p`.
17−
18−### Syntax
19−
20−Irregular: any [warm atom](../warm/) form, prefixed with `%`.
21−
22−Irregular: e.g., `%hi`. Character constraints: `a-z`
23−lowercase to start, `a-z` or `0-9` thereafter, with infix
24−hyphens (`hep`), "kebab-case."
25−
26−Irregular: `~`.
27−
28−### Examples
29−
30−We can see the contrast with warm atoms by using the compiler parser function, `ream`:
31−
32−```
33−> (ream '%hi')
34−[%rock p=%tas q=26.984]
35−
36−> (ream '\'hi\'')
37−[%sand p=%t q=26.984]
38−
39−> (ream '%12')
40−[%rock p=%ud q=12]
41−```
reference/hoon-expressions/rune/constants/path.udondeleted−35
@@ -1,35 +0,0 @@
1−:- :~ navhome/'/docs/'
2− navuptwo/'true'
3− sort/'4'
4− title/'Paths'
5− ==
6−;>
7−
8−# Paths
9−
10−`[%path p=(list (each @ta hoon))]`: path with interpolation.
11−
12−### Produces
13−
14−A null-terminated list of the items in `p`, which are either constant
15−`@ta` atoms (`knots`), or expressions producing a `knot`.
16−
17−### Syntax
18−
19−Irregular: `/this/is/a/path`.
20−
21−### Examples
22−
23−```
24−> `path`/this/is/a/path
25−/this/is/a/path
26−
27−> `path`/this/is/[`@ta`(cat 3 %a- %test)]/path
28−/this/is/a-test/path
29−
30−> `path`/this/is/(scot %tas 'test')/path
31−/this/is/test/path
32−
33−> /
34−~
35−```
reference/hoon-expressions/rune/constants/text.udondeleted−54
@@ -1,54 +0,0 @@
1−:- :~ navhome/'/docs/'
2− navuptwo/'true'
3− sort/'3'
4− title/'Strings'
5− ==
6−;>
7−
8−# Strings with Interpolation
9−
10−`[%knit p=(list (each @t hoon))]`: text string with interpolation.
11−
12−### Produces
13−
14−A tape.
15−
16−### Syntax
17−
18−Irregular: `"abcdefg"`.
19−
20−Irregular: `"abc{(weld "lmnop" "xyz")}defg"`.
21−
22−```
23−> "abcdefg"
24−"abcdefg"
25−
26−> "abc{(weld "lmnop" "xyz")}defg"
27−"abclmnopxyzdefg"
28−
29−> (ream '"abcdefg"')
30−[%knit p=~[97 98 99 100 101 102 103]]
31−```
32−
33−### Examples
34−
35−String:
36−
37−```
38−> "hello, world."
39−"hello, world."
40−```
41−
42−String with interpolation:
43−
44−```
45−> =+(planet="world" "hello, {planet}.")
46−"hello, world."
47−```
48−
49−String with interpolated prettyprinting:
50−
51−```
52−> =+(planet=%world "hello, {<planet>}.")
53−"hello, %world."
54−```
reference/hoon-expressions/rune/constants/warm.udondeleted−76
@@ -1,76 +0,0 @@
1−:- :~ navhome/'/docs/'
2− navuptwo/'true'
3− sort/'1'
4− title/'Warm Atoms'
5− ==
6−;>
7−
8−# Warm Atoms
9−
10−`[%sand p=term q=@]`; a constant, warm atom.
11−
12−A 'warm' atom is one whose type is inferred to be general, i.e., not just a single atom type.
13−
14−```
15−> `@`12
16−12
17−
18−> `%12`12
19−nest-fail
20−```
21−
22−### Produces
23−
24−A warm (variable) atom `q` with aura `p`. Use the Hoon compiler parser function `ream` to take a closer look:
25−
26−```
27−> (ream '12')
28−[%sand p=%ud q=12]
29−
30−> (ream '\'Hello!\'')
31−[%sand p=%t q=36.762.444.129.608]
32−```
33−
34−### Syntax by example
35−
36−Irregular. A table of examples:
37−
38−```
39−@c UTF-32 ~-foobar
40−@da 128-bit absolute date ~2016.4.23..20.09.26..f27b..dead..beef..babe
41− ~2016.4.23
42−@dr 128-bit relative date ~s17 (17 seconds)
43− ~m20 (20 minutes)
44− ~d42 (42 days)
45−@f loobean & (0, yes)
46− | (1, no)
47−@p ~zod (0)
48−@rd 64-bit IEEE float .~3.14 (pi)
49− .~-3.14 (negative pi)
50−@rs 32-bit IEEE float .3.14 (pi)
51− .-3.14 (negative pi)
52−@rq 128-bit IEEE float .~~~3.14 (pi)
53−@rh 16-bit IEEE float .~~3.14 (pi)
54−@sb signed binary --0b10 (2)
55− -0b101 (-5)
56−@sd signed decimal --2 (2)
57− -5 (-5)
58−@sv signed base32 --0v68 (200)
59− -0vfk (-500)
60−@sw signed base64 --0w38 (200)
61− -0w7Q (500)
62−@sx signed hexadecimal --0x2 (2)
63− -0x5 -5
64−@t UTF-8 text (cord) 'foobar'
65−@ta ASCII text (knot) ~.foobar
66−@ub unsigned binary 0b10 (2)
67−@uc bitcoin address 0c1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa
68−@ud unsigned decimal 42 (42)
69− 1.420 (1420)
70−@uv unsigned base32 0v3ic5h.6urr6
71−@uw unsigned base64 0wsC5.yrSZC
72−@ux unsigned hexadecimal 0xcafe.babe
73−```
74−
75−The `@uv` characters are `0-9`, `a-v`. The `@uw` characters are
76−`0-9`, `a-z`, `A-Z`, `-` and `~`.
reference/hoon-expressions/rune/dot.udon+233−1
@@ -11,4 +11,236 @@ Anything Nock can do, Hoon can do also. These runes are used for carrying out N
11
11
12## Runes
12## Runes
13
13
14−;list(datapreview "true", classname "runes");
14+;=
15+ ;h3
16+ ;div(id "dotket"): .^ "dotket"
17+ ==
18+==
19+
20+`[%dtkt p=spec q=hoon]`: load from the Arvo namespace with a fake Nock instruction: 'Nock `12`''.
21+
22+##### Produces
23+
24+The noun `q`, cast to the type `p`.
25+
26+##### Discussion
27+
28+Nock has no `12` instruction! But the virtual Nock
29+used to run userspace code does. Nock `12` loads from a
30+typed immutable namespace defined by its virtual context.
31+
32+Ordinarily a Hoon expression has access to no information but whatever can be found in the subject. The one exception is with the `.^` rune. It essentially allows you to request information from one of the Arvo vanes (modules).
33+
34+`.^` checks that the type of the value retrieved from Arvo nests under `p`. `p` is a `path` which includes information about which vane is being queried, and what sort of information is requested.
35+
36+In principle `.^` takes two subexpressions, but in practice `q` is often given in two parts: the first part includes the vane to be queried (e.g., `%a` for Ames, `%b` for Behn, `%c` for Clay, etc.) and the kind of request. The second part is a path that corresponds to the kind of request.
37+
38+##### Examples
39+
40+In the dojo we can ask Clay -- the Arvo filesystem -- for a listing of the files at our current path, `%`:
41+
42+```
43+> .^(arch %cy %)
44+[ fil=~
45+ dir
46+ { [p=~.web q=~]
47+ [p=~.LICENSE q=~]
48+ [p=~.app q=~]
49+ [p=~.lib q=~]
50+ [p=~.sec q=~]
51+ [p=~.sys q=~]
52+ [p=~.ren q=~]
53+ [p=~.sur q=~]
54+ [p=~.tests q=~]
55+ [p=~.mar q=~]
56+ [p=~.gen q=~]
57+ }
58+]
59+```
60+
61+The `%c` is for Clay, and the `y` is for the request type. `arch` is the type of the listing. See `gen/cat.hoon` to see how this information is printed more prettily.
62+
63+The `%` is for the current path in the dojo:
64+
65+```
66+> `path`%
67+/~zod/home/~2018.9.20..23.05.35..0231
68+```
69+
70+You can modify the time of the file listing quite simply and ask for a listing from 5 hours ago. (Remember that Clay is a revision-controlled file system.)
71+
72+```
73+> .^(arch %cy /(scot %p our)/home/(scot %da (sub now ~h5)))
74+[ fil=~
75+ dir
76+ { [p=~.web q=~]
77+ [p=~.LICENSE q=~]
78+ [p=~.app q=~]
79+ [p=~.lib q=~]
80+ [p=~.sec q=~]
81+ [p=~.sys q=~]
82+ [p=~.ren q=~]
83+ [p=~.sur q=~]
84+ [p=~.tests q=~]
85+ [p=~.mar q=~]
86+ [p=~.gen q=~]
87+ }
88+]
89+```
90+
91+`our` is the value for your ship's name.
92+
93+;=
94+ ;h3
95+ ;div(id "dotlus"): .+ "dotlus"
96+ ==
97+==
98+
99+`[%dtls p=hoon]`: increment an atom with Nock `4`.
100+
101+##### Produces
102+
103+`p` plus `1` if `p` is an atom; otherwise, crashes. The product atom has no aura.
104+
105+##### Syntax
106+
107+Regular: *1-fixed*.
108+
109+Irregular: `+(6)` is `.+(6)`.
110+
111+##### Examples
112+
113+```
114+> .+(6)
115+7
116+
117+> +(6)
118+7
119+
120+> +(%foo)
121+7.303.015
122+
123+> +([1 2])
124+nest-fail
125+```
126+
127+;=
128+ ;h3
129+ ;div(id "dottar"): .* "dottar"
130+ ==
131+==
132+
133+`[%dttr p=hoon q=hoon]`: evaluate with Nock `2`.
134+
135+##### Produces
136+
137+Nock of formula `q` and subject `p`, with type `%noun`.
138+
139+##### Syntax
140+
141+Regular: *2-fixed*.
142+
143+##### Discussion
144+
145+`.*(p q)` is used to run Nock formula `p` on the subject `q` from within Hoon.
146+
147+Keep in mind that `p` and `q` can be arbitrary Hoon expressions, as long as they evaluate to the appropriate nouns for Nock evaluation.
148+
149+Note also that `.*` ("dottar") can be used to bypass the type system. It's
150+therefore possible to use Hoon as a typeless language.
151+
152+##### Examples
153+
154+```
155+> .*([20 30] [0 2])
156+20
157+
158+> .*(33 [4 0 1])
159+34
160+
161+> .*(|.(50) [9 2 0 1])
162+50
163+
164+> .*(12 [7 [`1 [4 `1]] [`2 `3 `2]])
165+[12 13 12]
166+
167+> .*(~ [5 1^4 [4 1^3]])
168+0
169+
170+> .*(~ [5 1^5 [4 1^3]])
171+1
172+```
173+
174+;=
175+ ;h3
176+ ;div(id "dottis"): .= "dottis"
177+ ==
178+==
179+
180+`[%dtts p=hoon q=hoon]`: test for equality with Nock `5`.
181+
182+##### Produces
183+
184+`%.y` if `p` equals `q`; otherwise `%.n`.
185+
186+##### Syntax
187+
188+Regular: *2-fixed*.
189+
190+Irregular: `=(a b)` is `.=(a b)`.
191+
192+##### Discussion
193+
194+The test for equality includes a type check. Either the type of `p` must nest under the type of `q`, or _vice versa_. Otherwise the result is a crash.
195+
196+Like Nock equality, `.=` ("dottis") tests whether two nouns are the same,
197+ignoring invisible pointer structure. Because in a conventional
198+noun implementation each noun has a lazy short hash, comparisons
199+are fast unless the hash needs to be computed, or we are comparing
200+separate copies of identical nouns. (Comparing large duplicates
201+is a common cause of performance bugs.)
202+
203+##### Examples
204+
205+```
206+> .=(0 0)
207+%.y
208+
209+> =(0 0)
210+%.y
211+
212+> .=(1 2)
213+%.n
214+
215+> =(1 2)
216+%.n
217+
218+> =(12 [12 14])
219+nest-fail
220+```
221+
222+;=
223+ ;h3
224+ ;div(id "dotwut"): .? "dotwut"
225+ ==
226+==
227+
228+`[%dtwt p=hoon]`: test for cell or atom with Nock `3`.
229+
230+##### Produces
231+
232+`%.y` if `p` is a cell; otherwise `%.n`.
233+
234+##### Syntax
235+
236+Regular: *1-fixed*.
237+
238+##### Examples
239+
240+```
241+> .?(42)
242+%.n
243+
244+> .?([42 43])
245+%.y
246+```
reference/hoon-expressions/rune/dot/ket.udondeleted−80
@@ -1,80 +0,0 @@
1−:- :~ navhome/'/docs/'
2− sort/'5'
3− title/'.^ "dotket"'
4− ==
5−;>
6−
7−# `.^ "dotket"`
8−
9−`[%dtkt p=spec q=hoon]`: load from the Arvo namespace with a fake Nock instruction: 'Nock `12`''.
10−
11−## Produces
12−
13−The noun `q`, cast to the type `p`.
14−
15−## Discussion
16−
17−Nock has no `12` instruction! But the virtual Nock
18−used to run userspace code does. Nock `12` loads from a
19−typed immutable namespace defined by its virtual context.
20−
21−Ordinarily a Hoon expression has access to no information but whatever can be found in the subject. The one exception is with the `.^` rune. It essentially allows you to request information from one of the Arvo vanes (modules).
22−
23−`.^` checks that the type of the value retrieved from Arvo nests under `p`. `p` is a `path` which includes information about which vane is being queried, and what sort of information is requested.
24−
25−In principle `.^` takes two subexpressions, but in practice `q` is often given in two parts: the first part includes the vane to be queried (e.g., `%a` for Ames, `%b` for Behn, `%c` for Clay, etc.) and the kind of request. The second part is a path that corresponds to the kind of request.
26−
27−## Examples
28−
29−In the dojo we can ask Clay -- the Arvo filesystem -- for a listing of the files at our current path, `%`:
30−
31−```
32−> .^(arch %cy %)
33−[ fil=~
34− dir
35− { [p=~.web q=~]
36− [p=~.LICENSE q=~]
37− [p=~.app q=~]
38− [p=~.lib q=~]
39− [p=~.sec q=~]
40− [p=~.sys q=~]
41− [p=~.ren q=~]
42− [p=~.sur q=~]
43− [p=~.tests q=~]
44− [p=~.mar q=~]
45− [p=~.gen q=~]
46− }
47−]
48−```
49−
50−The `%c` is for Clay, and the `y` is for the request type. `arch` is the type of the listing. See `gen/cat.hoon` to see how this information is printed more prettily.
51−
52−The `%` is for the current path in the dojo:
53−
54−```
55−> `path`%
56−/~zod/home/~2018.9.20..23.05.35..0231
57−```
58−
59−You can modify the time of the file listing quite simply and ask for a listing from 5 hours ago. (Remember that Clay is a revision-controlled file system.)
60−
61−```
62−> .^(arch %cy /(scot %p our)/home/(scot %da (sub now ~h5)))
63−[ fil=~
64− dir
65− { [p=~.web q=~]
66− [p=~.LICENSE q=~]
67− [p=~.app q=~]
68− [p=~.lib q=~]
69− [p=~.sec q=~]
70− [p=~.sys q=~]
71− [p=~.ren q=~]
72− [p=~.sur q=~]
73− [p=~.tests q=~]
74− [p=~.mar q=~]
75− [p=~.gen q=~]
76− }
77−]
78−```
79−
80−`our` is the value for your ship's name.
reference/hoon-expressions/rune/dot/lus.udondeleted−36
@@ -1,36 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'3'
4− title/'.+ "dotlus"'
5− ==
6−;>
7−
8−# `.+ "dotlus"`
9−
10−`[%dtls p=hoon]`: increment an atom with Nock `4`.
11−
12−## Produces
13−
14−`p` plus `1` if `p` is an atom; otherwise, crashes. The product atom has no aura.
15−
16−## Syntax
17−
18−Regular: *1-fixed*.
19−
20−Irregular: `+(6)` is `.+(6)`.
21−
22−## Examples
23−
24−```
25−> .+(6)
26−7
27−
28−> +(6)
29−7
30−
31−> +(%foo)
32−7.303.015
33−
34−> +([1 2])
35−nest-fail
36−```
reference/hoon-expressions/rune/dot/tar.udondeleted−49
@@ -1,49 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'1'
4− title/'.* "dottar"'
5− ==
6−;>
7−
8−# `.* "dottar"`
9−
10−`[%dttr p=hoon q=hoon]`: evaluate with Nock `2`.
11−
12−## Produces
13−
14−Nock of formula `q` and subject `p`, with type `%noun`.
15−
16−## Syntax
17−
18−Regular: *2-fixed*.
19−
20−## Discussion
21−
22−`.*(p q)` is used to run Nock formula `p` on the subject `q` from within Hoon.
23−
24−Keep in mind that `p` and `q` can be arbitrary Hoon expressions, as long as they evaluate to the appropriate nouns for Nock evaluation.
25−
26−Note also that `.*` ("dottar") can be used to bypass the type system. It's
27−therefore possible to use Hoon as a typeless language.
28−
29−## Examples
30−
31−```
32−> .*([20 30] [0 2])
33−20
34−
35−> .*(33 [4 0 1])
36−34
37−
38−> .*(|.(50) [9 2 0 1])
39−50
40−
41−> .*(12 [7 [`1 [4 `1]] [`2 `3 `2]])
42−[12 13 12]
43−
44−> .*(~ [5 1^4 [4 1^3]])
45−0
46−
47−> .*(~ [5 1^5 [4 1^3]])
48−1
49−```
reference/hoon-expressions/rune/dot/tis.udondeleted−50
@@ -1,50 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'4'
4− title/'.= "dottis"'
5− ==
6−;>
7−
8−# `.= "dottis"`
9−
10−`[%dtts p=hoon q=hoon]`: test for equality with Nock `5`.
11−
12−## Produces
13−
14−%.y` if `p` equals `q`; otherwise `%.n`.
15−
16−## Syntax
17−
18−Regular: *2-fixed*.
19−
20−Irregular: `=(a b)` is `.=(a b)`.
21−
22−## Discussion
23−
24−The test for equality includes a type check. Either the type of `p` must nest under the type of `q`, or _vice versa_. Otherwise the result is a crash.
25−
26−Like Nock equality, `.=` ("dottis") tests whether two nouns are the same,
27−ignoring invisible pointer structure. Because in a conventional
28−noun implementation each noun has a lazy short hash, comparisons
29−are fast unless the hash needs to be computed, or we are comparing
30−separate copies of identical nouns. (Comparing large duplicates
31−is a common cause of performance bugs.)
32−
33−## Examples
34−
35−```
36−> .=(0 0)
37−%.y
38−
39−> =(0 0)
40−%.y
41−
42−> .=(1 2)
43−%.n
44−
45−> =(1 2)
46−%.n
47−
48−> =(12 [12 14])
49−nest-fail
50−```
reference/hoon-expressions/rune/dot/wut.udondeleted−28
@@ -1,28 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'2'
4− title/'.? "dotwut"'
5− ==
6−;>
7−
8−# `.? "dotwut"`
9−
10−`[%dtwt p=hoon]`: test for cell or atom with Nock `3`.
11−
12−## Produces
13−
14−`%.y` if `p` is a cell; otherwise `%.n`.
15−
16−## Syntax
17−
18−Regular: *1-fixed*.
19−
20−## Examples
21−
22−```
23−> .?(42)
24−%.n
25−
26−> .?([42 43])
27−%.y
28−```
reference/hoon-expressions/rune/ket.udon+414−3
@@ -7,8 +7,8 @@
7
7
8# Casts `^` ("ket")
8# Casts `^` ("ket")
9
9
10−[`^-` ("kethep")](./hep/), [`^+` ("ketlus")](./lus/), and
10+[`^-` ("kethep")](#kethep), [`^+` ("ketlus")](#ketlus), and
11−[`^=` ("kettis")](./tis/) let us adjust types without violating type
11+[`^=` ("kettis")](#kettis) let us adjust types without violating type
12constraints.
12constraints.
13
13
14The `nest` algorithm which tests subtyping is conservative;
14The `nest` algorithm which tests subtyping is conservative;
@@ -16,4 +16,415 @@ it never allows invalid nests, it sometimes rejects valid nests.
16
16
17## Runes
17## Runes
18
18
19−;list(datapreview "true", classname "runes");
19+;=
20+ ;h3
21+ ;div(id "ketbar"): ^| "ketbar"
22+ ==
23+==
24+
25+`[%ktbr p=hoon]`: convert a gold core to an iron core (contravariant).
26+
27+##### Produces
28+
29+`p` as an iron core; crash if not a gold core.
30+
31+##### Syntax
32+
33+Regular: *1-fixed*.
34+
35+##### Discussion
36+
37+An iron core is an opaque function (gate or door).
38+
39+Theorem: if type `x` nests within type `a`, and type `y` nests
40+within type `b`, a core accepting `b` and producing `x` nests
41+within a iron core accepting `y` and producing `a`.
42+
43+Informally, a function fits an interface if the function has a
44+more specific result and/or a less specific argument than the
45+interface.
46+
47+##### Examples
48+
49+The prettyprinter shows the core metal (`.` gold, `|` iron):
50+
51+```
52+~zod:dojo> |=(@ 1)
53+<1.gcq [@ @n <250.yur 41.wda 374.hzt 100.kzl 1.ypj %151>]>
54+
55+~zod:dojo> ^|(|=(@ 1))
56+<1|gcq [@ @n <250.yur 41.wda 374.hzt 100.kzl 1.ypj %151>]>
57+```
58+
59+;=
60+ ;h3
61+ ;div(id "ketcol"): ^: "ketcol"
62+ ==
63+==
64+
65+`[%ktcl p=spec]`: 'factory' gate for type `p`.
66+
67+##### Produces
68+
69+A gate that returns the sample value if it's of the correct type, but crashes otherwise.
70+
71+##### Syntax
72+
73+Regular: *1-fixed*.
74+
75+##### Discussion
76+
77+In older versions of Hoon, a 'mold' was an idempotent gate that was guaranteed to produce a noun of that type. If an input value wasn't of the correct type, the bunt value of that type was returned. (See `^*`.)
78+
79+`^:` is used to produce a gate that is much like a mold, except that instead of producing a bunt value when the input value is of the wrong type, it crashes.
80+
81+##### Examples
82+
83+```
84+> ^: @
85+< 1.goa
86+ { *
87+ {our/@p now/@da eny/@uvJ}
88+ <19.hqf 23.byz 5.mzd 36.apb 119.zmz 238.ipu 51.mcd 93.glm 74.dbd 1.qct $141>
89+ }
90+>
91+
92+> (^:(@) 22)
93+22
94+
95+> (^:(@) [22 33])
96+ford: %ride failed to execute:
97+```
98+
99+;=
100+ ;h3
101+ ;div(id "ketdot"): ^. "ketdot"
102+ ==
103+==
104+
105+`[%ktdt p=hoon q=hoon]`: typecast on value produced by passing `q` to `p`.
106+
107+##### Expands to
108+
109+```
110+^+(%:(p q) q)
111+```
112+
113+##### Syntax
114+
115+Regular: *2-fixed*.
116+
117+```
118+^. p=hoon q=hoon
119+```
120+
121+##### Discussion
122+
123+`p` produces a gate and q is any Hoon expression.
124+
125+`^.` is particularly useful when `p` is a gate that 'cleans up' the type information about some piece of data. For example, `limo` is used to turn a raw noun of the appropriate shape into a genuine list. Hence we can use `^.` to cast with `limo` and similar gates, ensuring that the product has the desired type.
126+
127+##### Examples
128+
129+```
130+> =mylist [11 22 33 ~]
131+
132+> ?~(mylist ~ i.mylist)
133+mint-vain
134+
135+> =mylist ^.(limo mylist)
136+
137+> ?~(mylist ~ i.mylist)
138+11
139+
140+> ?~(mylist ~ t.mylist)
141+~[22 33]
142+```
143+
144+;=
145+ ;h3
146+ ;div(id "kethep"): ^- "kethep"
147+ ==
148+==
149+
150+`[%kthp p=spec q=hoon]`: typecast by explicit type label.
151+
152+##### Expands to
153+
154+```
155+^+(^*(p) q)
156+```
157+
158+##### Syntax
159+
160+Regular: *2-fixed*.
161+
162+Irregular: `` `foo`baz`` is `^-(foo baz)`.
163+
164+##### Discussion
165+
166+It's a good practice to put a `^-` ("kethep") at the top of every arm
167+(including gates, loops, etc). This cast is strictly necessary
168+only in the presence of head recursion (otherwise you'll get a
169+`rest-loop` error, or if you really screw up spectacularly an
170+infinite loop in the compiler).
171+
172+##### Examples
173+
174+```
175+~zod:dojo> (add 90 7)
176+97
177+
178+~zod:dojo> `@t`(add 90 7)
179+'a'
180+
181+~zod:dojo> ^-(@t (add 90 7))
182+'a'
183+
184+/~zod:dojo> =foo |= a=@tas
185+ ^- (unit @ta)
186+ `a
187+
188+/~zod:dojo> (foo 97)
189+[~ ~.a]
190+```
191+
192+;=
193+ ;h3
194+ ;div(id "ketlus"): ^. "ketlus"
195+ ==
196+==
197+
198+`[%ktls p=hoon q=hoon]`: typecast by inferred type.
199+
200+##### Produces
201+
202+The value of `q` with the type of `p`, if the type of `q` nests within the type of `p`. Otherwise, `nest-fail`.
203+
204+##### Syntax
205+
206+Regular: *2-fixed*.
207+
208+##### Examples
209+
210+```
211+~zod:dojo> ^+('text' %a)
212+'a'
213+```
214+
215+;=
216+ ;h3
217+ ;div(id "ketpad"): ^& "ketpad"
218+ ==
219+==
220+
221+`[%ktpd p=hoon]`: convert a core to a zinc core (covariant).
222+
223+##### Produces
224+
225+`p` as a zinc core; crash if `p` isn't a gold or zinc core.
226+
227+##### Syntax
228+
229+Regular: *1-fixed*.
230+
231+##### Discussion
232+
233+A zinc core has a read-only sample and an opaque context. See [Advanced types](/docs/reference/hoon-expressions/advanced).
234+
235+##### Examples
236+
237+The prettyprinter shows the core metal in the arm labels `1.xoz` and `1&xoz` below (`.` is gold, `&` is zinc):
238+
239+```
240+> |=(@ 1)
241+< 1.xoz
242+ { @
243+ {our/@p now/@da eny/@uvJ}
244+ <19.hqf 23.byz 5.mzd 36.apb 119.zmz 238.ipu 51.mcd 93.glm 74.dbd 1.qct $141>
245+ }
246+>
247+
248+> ^&(|=(@ 1))
249+< 1&xoz
250+ { @
251+ {our/@p now/@da eny/@uvJ}
252+ <19.hqf 23.byz 5.mzd 36.apb 119.zmz 238.ipu 51.mcd 93.glm 74.dbd 1.qct $141>
253+ }
254+>
255+```
256+
257+You can read from the sample of a zinc core, but not change it:
258+
259+```
260+> =mycore ^&(|=(a=@ 1))
261+
262+> a.mycore
263+0
264+
265+> mycore(a 22)
266+-tack.a
267+-find.a
268+ford: %slim failed:
269+ford: %ride failed to compute type:
270+```
271+
272+;=
273+ ;h3
274+ ;div(id "ketsig"): ^~ "ketsig"
275+ ==
276+==
277+
278+`[%ktsg p=hoon]`: fold constant at compile time.
279+
280+##### Produces
281+
282+`p`, folded as a constant if possible.
283+
284+##### Syntax
285+
286+Regular: *1-fixed*.
287+
288+##### Examples
289+
290+```
291+~zod:dojo> (make '|-(42)')
292+[%8 p=[%1 p=[1 42]] q=[%9 p=2 q=[%0 p=1]]]
293+
294+~zod:dojo> (make '^~(|-(42))')
295+[%1 p=42]
296+```
297+
298+;=
299+ ;h3
300+ ;div(id "kettar"): ^* "kettar"
301+ ==
302+==
303+
304+`[%kttr p=spec]`: Produce example type value.
305+
306+##### Produces
307+
308+A default value (i.e., 'bunt value') of the type `p`.
309+
310+##### Syntax
311+
312+Regular: *1-fixed*.
313+
314+```
315+^* p=spec
316+```
317+
318+Irregular: `*p`.
319+
320+`p` is any structure expression.
321+
322+##### Examples
323+
324+Regular:
325+
326+```
327+> ^* @
328+0
329+
330+> ^* %baz
331+%baz
332+
333+> ^* ^
334+[0 0]
335+
336+> ^* ?
337+%.y
338+```
339+
340+Irregular:
341+
342+```
343+> *@
344+0
345+
346+> *^
347+[0 0]
348+
349+> *tape
350+""
351+```
352+
353+;=
354+ ;h3
355+ ;div(id "kettis"): ^= "kettis"
356+ ==
357+==
358+
359+`[%ktts p=skin q=hoon]`: Bind name to a value.
360+
361+##### Produces
362+
363+If `p` is a term, the product `q` with type `[%face p q]`. `p`
364+may also be a tuple of terms, or a term-skin pair; the type of
365+`q` must divide evenly into cells to match it.
366+
367+##### Syntax
368+
369+Regular: *2-fixed*.
370+
371+Irregular: `foo=baz` is `^=(foo baz)`.
372+
373+##### Examples
374+
375+```
376+~zod:dojo> a=1
377+a=1
378+
379+~zod:dojo> ^= a
380+ 1
381+a=1
382+
383+~zod:dojo> ^=(a 1)
384+a=1
385+
386+~zod:dojo> [b c d]=[1 2 3 4]
387+[b=1 c=2 d=[3 4]]
388+
389+~zod:dojo> [b c d=[x y]]=[1 2 3 4]
390+[b=1 c=2 d=[x=3 y4]]
391+```
392+
393+;=
394+ ;h3
395+ ;div(id "ketwut"): ^? "ketwut"
396+ ==
397+==
398+
399+`[%ktwt p=hoon]`: convert any core to a lead core (bivariant).
400+
401+##### Produces
402+
403+`p` as a lead core; crash if not a core.
404+
405+##### Syntax
406+
407+Regular: *1-fixed*.
408+
409+##### Discussion
410+
411+A lead core is an opaque generator; the payload can't be read or
412+written.
413+
414+Theorem: if type `x` nests within type `a`, a lead core producing
415+`x` nests within a lead core producing `a`.
416+
417+Informally, a more specific generator can be used as a less
418+specific generator.
419+
420+##### Examples
421+
422+The prettyprinter shows the core metal (`.` gold, `?` lead):
423+
424+```
425+~zod:dojo> |=(@ 1)
426+<1.gcq [@ @n <250.yur 41.wda 374.hzt 100.kzl 1.ypj %151>]>
427+
428+~zod:dojo> ^?(|=(@ 1))
429+<1?gcq [@ @n <250.yur 41.wda 374.hzt 100.kzl 1.ypj %151>]>
430+```
reference/hoon-expressions/rune/ket/bar.udondeleted−42
@@ -1,42 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'5'
4− title/'^| "ketbar"'
5− ==
6−;>
7−
8−# `^| "ketbar"`
9−
10−`[%ktbr p=hoon]`: convert a gold core to an iron core (contravariant).
11−
12−## Produces
13−
14−`p` as an iron core; crash if not a gold core.
15−
16−## Syntax
17−
18−Regular: *1-fixed*.
19−
20−## Discussion
21−
22−An iron core is an opaque function (gate or door).
23−
24−Theorem: if type `x` nests within type `a`, and type `y` nests
25−within type `b`, a core accepting `b` and producing `x` nests
26−within a iron core accepting `y` and producing `a`.
27−
28−Informally, a function fits an interface if the function has a
29−more specific result and/or a less specific argument than the
30−interface.
31−
32−## Examples
33−
34−The prettyprinter shows the core metal (`.` gold, `|` iron):
35−
36−```
37−~zod:dojo> |=(@ 1)
38−<1.gcq [@ @n <250.yur 41.wda 374.hzt 100.kzl 1.ypj %151>]>
39−
40−~zod:dojo> ^|(|=(@ 1))
41−<1|gcq [@ @n <250.yur 41.wda 374.hzt 100.kzl 1.ypj %151>]>
42−```
reference/hoon-expressions/rune/ket/col.udondeleted−42
@@ -1,42 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'10'
4− title/'^: "ketcol"'
5− ==
6−;>
7−
8−# `^: "ketcol"`
9−
10−`[%ktcl p=spec]`: 'factory' gate for type `p`.
11−
12−## Produces
13−
14−A gate that returns the sample value if it's of the correct type, but crashes otherwise.
15−
16−## Syntax
17−
18−Regular: *1-fixed*.
19−
20−## Discussion
21−
22−In older versions of Hoon, a 'mold' was an idempotent gate that was guaranteed to produce a noun of that type. If an input value wasn't of the correct type, the bunt value of that type was returned. (See `^*`.)
23−
24−`^:` is used to produce a gate that is much like a mold, except that instead of producing a bunt value when the input value is of the wrong type, it crashes.
25−
26−## Examples
27−
28−```
29−> ^: @
30−< 1.goa
31− { *
32− {our/@p now/@da eny/@uvJ}
33− <19.hqf 23.byz 5.mzd 36.apb 119.zmz 238.ipu 51.mcd 93.glm 74.dbd 1.qct $141>
34− }
35−>
36−
37−> (^:(@) 22)
38−22
39−
40−> (^:(@) [22 33])
41−ford: %ride failed to execute:
42−```
reference/hoon-expressions/rune/ket/dot.udondeleted−47
@@ -1,47 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'7'
4− title/'^. "ketdot"'
5− ==
6−;>
7−
8−# `^. "ketdot"`
9−
10−`[%ktdt p=hoon q=hoon]`: typecast on value produced by passing `q` to `p`.
11−
12−## Expands to
13−
14−```
15−^+(%:(p q) q)
16−```
17−
18−## Syntax
19−
20−Regular: *2-fixed*.
21−
22−```
23−^. p=hoon q=hoon
24−```
25−
26−## Discussion
27−
28−`p` produces a gate and q is any Hoon expression.
29−
30−`^.` is particularly useful when `p` is a gate that 'cleans up' the type information about some piece of data. For example, `limo` is used to turn a raw noun of the appropriate shape into a genuine list. Hence we can use `^.` to cast with `limo` and similar gates, ensuring that the product has the desired type.
31−
32−## Examples
33−
34−```
35−> =mylist [11 22 33 ~]
36−
37−> ?~(mylist ~ i.mylist)
38−mint-vain
39−
40−> =mylist ^.(limo mylist)
41−
42−> ?~(mylist ~ i.mylist)
43−11
44−
45−> ?~(mylist ~ t.mylist)
46−~[22 33]
47−```
reference/hoon-expressions/rune/ket/hep.udondeleted−50
@@ -1,50 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'1'
4− title/'^- "kethep"'
5− ==
6−;>
7−
8−# `^- "kethep"`
9−
10−`[%kthp p=spec q=hoon]`: typecast by explicit type label.
11−
12−## Expands to
13−
14−```
15−^+(^*(p) q)
16−```
17−
18−## Syntax
19−
20−Regular: *2-fixed*.
21−
22−Irregular: `` `foo`baz`` is `^-(foo baz)`.
23−
24−## Discussion
25−
26−It's a good practice to put a `^-` ("kethep") at the top of every arm
27−(including gates, loops, etc). This cast is strictly necessary
28−only in the presence of head recursion (otherwise you'll get a
29−`rest-loop` error, or if you really screw up spectacularly an
30−infinite loop in the compiler).
31−
32−## Examples
33−
34−```
35−~zod:dojo> (add 90 7)
36−97
37−
38−~zod:dojo> `@t`(add 90 7)
39−'a'
40−
41−~zod:dojo> ^-(@t (add 90 7))
42−'a'
43−
44−/~zod:dojo> =foo |= a=@tas
45− ^- (unit @ta)
46− `a
47−
48−/~zod:dojo> (foo 97)
49−[~ ~.a]
50−```
reference/hoon-expressions/rune/ket/lus.udondeleted−25
@@ -1,25 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'2'
4− title/'^+ "ketlus"'
5− ==
6−;>
7−
8−# `^+ "ketlus"`
9−
10−`[%ktls p=hoon q=hoon]`: typecast by inferred type.
11−
12−## Produces
13−
14−The value of `q` with the type of `p`, if the type of `q` nests within the type of `p`. Otherwise, `nest-fail`.
15−
16−## Syntax
17−
18−Regular: *2-fixed*.
19−
20−## Examples
21−
22−```
23−~zod:dojo> ^+('text' %a)
24−'a'
25−```
reference/hoon-expressions/rune/ket/pad.udondeleted−59
@@ -1,59 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'9'
4− title/'^& "ketpad"'
5− ==
6−;>
7−
8−# `^& "ketpad"`
9−
10−`[%ktpd p=hoon]`: convert a core to a zinc core (covariant).
11−
12−## Produces
13−
14−`p` as a zinc core; crash if `p` isn't a gold or zinc core.
15−
16−## Syntax
17−
18−Regular: *1-fixed*.
19−
20−## Discussion
21−
22−A zinc core has a read-only sample and an opaque context. See [Advanced types](../../../advanced).
23−
24−## Examples
25−
26−The prettyprinter shows the core metal in the arm labels `1.xoz` and `1&xoz` below (`.` is gold, `&` is zinc):
27−
28−```
29−> |=(@ 1)
30−< 1.xoz
31− { @
32− {our/@p now/@da eny/@uvJ}
33− <19.hqf 23.byz 5.mzd 36.apb 119.zmz 238.ipu 51.mcd 93.glm 74.dbd 1.qct $141>
34− }
35−>
36−
37−> ^&(|=(@ 1))
38−< 1&xoz
39− { @
40− {our/@p now/@da eny/@uvJ}
41− <19.hqf 23.byz 5.mzd 36.apb 119.zmz 238.ipu 51.mcd 93.glm 74.dbd 1.qct $141>
42− }
43−>
44−```
45−
46−You can read from the sample of a zinc core, but not change it:
47−
48−```
49−> =mycore ^&(|=(a=@ 1))
50−
51−> a.mycore
52−0
53−
54−> mycore(a 22)
55−-tack.a
56−-find.a
57−ford: %slim failed:
58−ford: %ride failed to compute type:
59−```
reference/hoon-expressions/rune/ket/sig.udondeleted−28
@@ -1,28 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'4'
4− title/'^~ "ketsig"'
5− ==
6−;>
7−
8−# `^~ "ketsig"`
9−
10−`[%ktsg p=hoon]`: fold constant at compile time.
11−
12−## Produces
13−
14−`p`, folded as a constant if possible.
15−
16−## Syntax
17−
18−Regular: *1-fixed*.
19−
20−## Examples
21−
22−```
23−~zod:dojo> (make '|-(42)')
24−[%8 p=[%1 p=[1 42]] q=[%9 p=2 q=[%0 p=1]]]
25−
26−~zod:dojo> (make '^~(|-(42))')
27−[%1 p=42]
28−```
reference/hoon-expressions/rune/ket/tar.udondeleted−57
@@ -1,57 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'8'
4− title/'^* "kettar"'
5− ==
6−;>
7−
8−# `^* "kettar"`
9−
10−`[%kttr p=spec]`: Produce example type value.
11−
12−## Produces
13−
14−A default value (i.e., 'bunt value') of the type `p`.
15−
16−## Syntax
17−
18−Regular: *1-fixed*.
19−
20−```
21−^* p=spec
22−```
23−
24−Irregular: `*p`.
25−
26−`p` is any structure expression.
27−
28−## Examples
29−
30−Regular:
31−
32−```
33−> ^* @
34−0
35−
36−> ^* %baz
37−%baz
38−
39−> ^* ^
40−[0 0]
41−
42−> ^* ?
43−%.y
44−```
45−
46−Irregular:
47−
48−```
49−> *@
50−0
51−
52−> *^
53−[0 0]
54−
55−> *tape
56−""
57−```
reference/hoon-expressions/rune/ket/tis.udondeleted−42
@@ -1,42 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'3'
4− title/'^= "kettis"'
5− ==
6−;>
7−
8−# `^= "kettis"`
9−
10−`[%ktts p=skin q=hoon]`: Bind name to a value.
11−
12−## Produces
13−
14−If `p` is a term, the product `q` with type `[%face p q]`. `p`
15−may also be a tuple of terms, or a term-skin pair; the type of
16−`q` must divide evenly into cells to match it.
17−
18−## Syntax
19−
20−Regular: *2-fixed*.
21−
22−Irregular: `foo=baz` is `^=(foo baz)`.
23−
24−## Examples
25−
26−```
27−~zod:dojo> a=1
28−a=1
29−
30−~zod:dojo> ^= a
31− 1
32−a=1
33−
34−~zod:dojo> ^=(a 1)
35−a=1
36−
37−~zod:dojo> [b c d]=[1 2 3 4]
38−[b=1 c=2 d=[3 4]]
39−
40−~zod:dojo> [b c d=[x y]]=[1 2 3 4]
41−[b=1 c=2 d=[x=3 y4]]
42−```
reference/hoon-expressions/rune/ket/wut.udondeleted−41
@@ -1,41 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'6'
4− title/'^? "ketwut"'
5− ==
6−;>
7−
8−# `^? "ketwut"`
9−
10−`[%ktwt p=hoon]`: convert any core to a lead core (bivariant).
11−
12−## Produces
13−
14−`p` as a lead core; crash if not a core.
15−
16−## Syntax
17−
18−Regular: *1-fixed*.
19−
20−## Discussion
21−
22−A lead core is an opaque generator; the payload can't be read or
23−written.
24−
25−Theorem: if type `x` nests within type `a`, a lead core producing
26−`x` nests within a lead core producing `a`.
27−
28−Informally, a more specific generator can be used as a less
29−specific generator.
30−
31−## Examples
32−
33−The prettyprinter shows the core metal (`.` gold, `?` lead):
34−
35−```
36−~zod:dojo> |=(@ 1)
37−<1.gcq [@ @n <250.yur 41.wda 374.hzt 100.kzl 1.ypj %151>]>
38−
39−~zod:dojo> ^?(|=(@ 1))
40−<1?gcq [@ @n <250.yur 41.wda 374.hzt 100.kzl 1.ypj %151>]>
41−```
reference/hoon-expressions/rune/lus.udon+178−1
@@ -15,4 +15,181 @@ There are various arm runes you can use to produce different kinds of arms. Nor
15
15
16## Runes
16## Runes
17
17
18−;list(datapreview "true", classname "runes");
18+;=
19+ ;h3
20+ ;div(id "lusbar"): +| "lusbar"
21+ ==
22+==
23+
24+Chapter label.
25+
26+##### Syntax
27+
28+Regular: *1-fixed*.
29+
30+```
31++| %label
32+```
33+
34+##### Discussion
35+
36+The `+|` doesn't produce an arm. It instead provides a label for the arms that follow it. The arms of a core can be divided into *chapters* for 'organization'. Chapter labels aren't part of the underlying noun of the core; they're stored as type system metadata only.
37+
38+See `tome` in the Hoon standard library.
39+
40+##### Examples
41+
42+Let's look at what the Hoon compiler's parser, `ream`, does with the `+|` rune:
43+
44+```
45+> (ream '|% +| %numbers ++ two 2 ++ three 3 --')
46+[ %brcn
47+ p=~
48+ q
49+ { [ p=%numbers
50+ q=[p=~ q={[p=%three q=[%sand p=%ud q=3]] [p=%two q=[%sand p=%ud q=2]]}]
51+ ]
52+ }
53+]
54+```
55+
56+Notice that `p.q` has the label `%numbers`. Contrast with:
57+
58+```
59+> (ream '|% ++ two 2 ++ three 3 --')
60+[ %brcn
61+ p=~
62+ q
63+ { [ p=%$
64+ q=[p=~ q={[p=%three q=[%sand p=%ud q=3]] [p=%two q=[%sand p=%ud q=2]]}]
65+ ]
66+ }
67+]
68+```
69+
70+;=
71+ ;h3
72+ ;div(id "lusbus"): +$ "lusbus"
73+ ==
74+==
75+
76+Produce a structure arm (type definition).
77+
78+##### Syntax
79+
80+Regular: *2-fixed*.
81+
82+```
83++$ p=term q=spec
84+```
85+
86+`p` is an arm name, and `q` is any structure expression.
87+
88+##### Discussion
89+
90+Arms produced by `+$` are essentially type definitions. They should be used when one wants to define custom types using core arms.
91+
92+The Hoon subexpression, `q`, must be a structure expression. That is, it must be either a basic structure expression (`*`, `~`, `^`, `?`, and `@`), or a complex expression made with the `$` family of runes (including irregular variants). Names of structures are also permitted (e.g., `tape`).
93+
94+##### Examples
95+
96+```
97+> =c |%
98+ +$ atom-pair $:(@ @)
99+ +$ flag-atom $:(? @)
100+ --
101+
102+> `atom-pair.c`[12 14]
103+[12 14]
104+
105+> `atom-pair.c`[12 [22 33]]
106+nest-fail
107+
108+> `flag-atom.c`[& 22]
109+[%.y 22]
110+```
111+
112+;=
113+ ;h3
114+ ;div(id "luslus"): ++ "luslus"
115+ ==
116+==
117+
118+Produce a normal arm.
119+
120+##### Syntax
121+
122+Regular: *2-fixed*.
123+
124+```
125+++ p=term q=hoon
126+```
127+
128+`p` is the arm name, and `q` is any Hoon expression.
129+
130+##### Discussion
131+
132+All arms must have a name (e.g., `add`). An arm is computed by name resolution. (This resolution is implicit in the case of `$` arms. See `|=`, `|-`, and `|^`.) The `++` rune is used for explicitly giving a name to an arm.
133+
134+Any Hoon expression, `q`, may be used to define the arm computation.
135+
136+##### Examples
137+
138+```
139+> =c |%
140+ ++ two 2
141+ ++ increment |=(a=@ +(a))
142+ --
143+
144+> two.c
145+2
146+
147+> (increment.c 11)
148+12
149+```
150+
151+;=
152+ ;h3
153+ ;div(id "lustar"): +* "lustar"
154+ ==
155+==
156+
157+
158+Produce a type constructor arm.
159+
160+##### Syntax
161+
162+Regular: *2-fixed*.
163+
164+```
165++* p=term [q=term] r=spec
166+```
167+
168+`p` is the arm name, `q` is the name of the argument for the constructor function enclosed in square brackets, and `r` is a structure expression that defines the constructor function.
169+
170+##### Discussion
171+
172+Arms produced by `+*` are essentially type constructors. They are used to construct new types from ones you already have. Consider `list`, which takes some type -- e.g., `@`, `tape`, etc. -- and returns a new type, e.g., `(list @)`, `(list tape)`, etc.
173+
174+The Hoon subexpression, `r`, must be a structure expression. That is, it must be either a basic structure expression (`*`, `~`, `^`, `?`, and `@`), or a complex expression made with the `$` family of runes (including irregular variants).
175+
176+##### Examples
177+
178+```
179+> =c |%
180+ +* triple [a] [a a a]
181+ +* wrap-flag [a] [? a]
182+ --
183+
184+> `(triple.c @)`[12 14 16]
185+[12 14 16]
186+
187+> `(triple.c ?)`[12 14 16]
188+nest-fail
189+
190+> `(triple.c ?)`[& | |]
191+[%.y %.n %.n]
192+
193+> `(wrap-flag.c @)`[& 22]
194+[%.y 22]
195+```
reference/hoon-expressions/rune/lus/bar.udondeleted−54
@@ -1,54 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'4'
4− title/'+| "lusbar"'
5− ==
6−;>
7−
8−# `+| "lusbar"`
9−
10−Chapter label.
11−
12−## Syntax
13−
14−Regular: *1-fixed*.
15−
16−```
17−+| %label
18−```
19−
20−## Discussion
21−
22−The `+|` doesn't produce an arm. It instead provides a label for the arms that follow it. The arms of a core can be divided into *chapters* for 'organization'. Chapter labels aren't part of the underlying noun of the core; they're stored as type system metadata only.
23−
24−See `tome` in the Hoon standard library.
25−
26−## Examples
27−
28−Let's look at what the Hoon compiler's parser, `ream`, does with the `+|` rune:
29−
30−```
31−> (ream '|% +| %numbers ++ two 2 ++ three 3 --')
32−[ %brcn
33− p=~
34− q
35− { [ p=%numbers
36− q=[p=~ q={[p=%three q=[%sand p=%ud q=3]] [p=%two q=[%sand p=%ud q=2]]}]
37− ]
38− }
39−]
40−```
41−
42−Notice that `p.q` has the label `%numbers`. Contrast with:
43−
44−```
45−> (ream '|% ++ two 2 ++ three 3 --')
46−[ %brcn
47− p=~
48− q
49− { [ p=%$
50− q=[p=~ q={[p=%three q=[%sand p=%ud q=3]] [p=%two q=[%sand p=%ud q=2]]}]
51− ]
52− }
53−]
54−```
reference/hoon-expressions/rune/lus/bus.udondeleted−44
@@ -1,44 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'2'
4− title/'+$ "lusbus"'
5− ==
6−;>
7−
8−# `+$ "lusbus"`
9−
10−Produce a structure arm (type definition).
11−
12−## Syntax
13−
14−Regular: *2-fixed*.
15−
16−```
17−+$ p=term q=spec
18−```
19−
20−`p` is an arm name, and `q` is any structure expression.
21−
22−## Discussion
23−
24−Arms produced by `+$` are essentially type definitions. They should be used when one wants to define custom types using core arms.
25−
26−The Hoon subexpression, `q`, must be a structure expression. That is, it must be either a basic structure expression (`*`, `~`, `^`, `?`, and `@`), or a complex expression made with the `$` family of runes (including irregular variants). Names of structures are also permitted (e.g., `tape`).
27−
28−## Examples
29−
30−```
31−> =c |%
32− +$ atom-pair $:(@ @)
33− +$ flag-atom $:(? @)
34− --
35−
36−> `atom-pair.c`[12 14]
37−[12 14]
38−
39−> `atom-pair.c`[12 [22 33]]
40−nest-fail
41−
42−> `flag-atom.c`[& 22]
43−[%.y 22]
44−```
reference/hoon-expressions/rune/lus/lus.udondeleted−41
@@ -1,41 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'1'
4− title/'++ "luslus"'
5− ==
6−;>
7−
8−# `++ "luslus"`
9−
10−Produce a normal arm.
11−
12−## Syntax
13−
14−Regular: *2-fixed*.
15−
16−```
17−++ p=term q=hoon
18−```
19−
20−`p` is the arm name, and `q` is any Hoon expression.
21−
22−## Discussion
23−
24−All arms must have a name (e.g., `add`). An arm is computed by name resolution. (This resolution is implicit in the case of `$` arms. See `|=`, `|-`, and `|^`.) The `++` rune is used for explicitly giving a name to an arm.
25−
26−Any Hoon expression, `q`, may be used to define the arm computation.
27−
28−## Examples
29−
30−```
31−> =c |%
32− ++ two 2
33− ++ increment |=(a=@ +(a))
34− --
35−
36−> two.c
37−2
38−
39−> (increment.c 11)
40−12
41−```
reference/hoon-expressions/rune/lus/tar.udondeleted−47
@@ -1,47 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'3'
4− title/'+* "lustar"'
5− ==
6−;>
7−
8−# `+* "lustar"`
9−
10−Produce a type constructor arm.
11−
12−## Syntax
13−
14−Regular: *2-fixed*.
15−
16−```
17−+* p=term [q=term] r=spec
18−```
19−
20−`p` is the arm name, `q` is the name of the argument for the constructor function enclosed in square brackets, and `r` is a structure expression that defines the constructor function.
21−
22−## Discussion
23−
24−Arms produced by `+*` are essentially type constructors. They are used to construct new types from ones you already have. Consider `list`, which takes some type -- e.g., `@`, `tape`, etc. -- and returns a new type, e.g., `(list @)`, `(list tape)`, etc.
25−
26−The Hoon subexpression, `r`, must be a structure expression. That is, it must be either a basic structure expression (`*`, `~`, `^`, `?`, and `@`), or a complex expression made with the `$` family of runes (including irregular variants).
27−
28−## Examples
29−
30−```
31−> =c |%
32− +* triple [a] [a a a]
33− +* wrap-flag [a] [? a]
34− --
35−
36−> `(triple.c @)`[12 14 16]
37−[12 14 16]
38−
39−> `(triple.c ?)`[12 14 16]
40−nest-fail
41−
42−> `(triple.c ?)`[& | |]
43−[%.y %.n %.n]
44−
45−> `(wrap-flag.c @)`[& 22]
46−[%.y 22]
47−```
reference/hoon-expressions/rune/mic.udon+393−2
@@ -5,10 +5,401 @@
5 ==
5 ==
6;>
6;>
7
7
8−# Make `;` ("sem")
8+# Make `;` ("mic")
9
9
10Miscellaneous useful macros.
10Miscellaneous useful macros.
11
11
12## Runes
12## Runes
13
13
14−;list(datapreview "true", classname "runes");
14+;=
15+ ;h3
16+ ;div(id "miccol"): ;: "miccol"
17+ ==
18+==
19+
20+`[%mccl p=hoon q=(list hoon)]`: call a binary function as an n-ary function.
21+
22+##### Expands to
23+
24+*Pseudocode*: `a`, `b`, `c`, ... as elements of `q`:
25+
26+Regular form:
27+
28+```
29+%-(p a %-(p b %-(p c ...)))
30+```
31+
32+Irregular form:
33+
34+```
35+(p a (p b (p c ...)))
36+```
37+
38+##### Compiler macro
39+
40+```
41+|-
42+?~ q !!
43+?~ t.q !!
44+?~ t.t.q
45+ (p i.q i.t.q)
46+(p i.q $(q t.q))
47+```
48+
49+##### Syntax
50+
51+Regular: *1-fixed*, then *running*.
52+
53+Irregular: `:(add a b c)` is `;:(add a b c)`.
54+
55+##### Examples
56+
57+```
58+~zod:dojo> (add 3 (add 4 5))
59+12
60+
61+~zod:dojo> ;:(add 3 4 5)
62+12
63+
64+~zod:dojo> :(add 3 4 5)
65+12
66+```
67+
68+;=
69+ ;h3
70+ ;div(id "miclus"): ;+ "miclus"
71+ ==
72+==
73+
74+make a single XML node (Sail)
75+
76+##### Produces
77+
78+A `marl`, i.e., a list of `manx`. A `manx` is a noun that represents a single XML node.
79+
80+##### Syntax
81+
82+*1-fixed*
83+
84+```
85+;+ p=hoon
86+```
87+
88+`p` is a Hoon expression that produces a `manx`.
89+
90+##### Discussion
91+
92+tl;dr -- `;+` converts a `manx` to a `marl`.
93+
94+`;+` is a Sail rune. Sail is a part of Hoon used for creating and operating on nouns that represent XML nodes. With the appropriate rendering pipeline, a Sail document can be used to generate a static website. See the [Sail tutorial](/docs/learn/arvo/arvo-internals/sail).
95+
96+In Sail a single XML node is represented by a `manx`. A single `<p>` node `manx` can be produced in the following way:
97+
98+```
99+> ;p: This will be rendered as an XML node.
100+[[%p ~] [[%$ [%$ "This will be rendered as an XML node."] ~] ~] ~]
101+```
102+
103+Sometimes what is needed is a `marl`, i.e., a list of `manx`. To convert a single `manx` to a `marl`, use the `;+` rune.
104+
105+One interesting thing about Sail is that it allows you to use complex Hoon expressions to choose from among several nodes to render. The `;+` rune can take such a complex expression.
106+
107+##### Examples
108+
109+```
110+> ^- marl
111+ ;+ ?: (gth 3 2)
112+ ;p: This is the node for 'yes'.
113+ ;p: This is the node for 'no'.
114+~[
115+ [ g=[n=%p a=~]
116+ c=[i=[g=[n=%$ a=~[[n=%$ v="This is the node for 'yes'."]]] c=~] t=~]
117+ ]
118+]
119+
120+> ^- marl
121+ ;+ ?: (gth 2 3)
122+ ;p: This is the node for 'yes'.
123+ ;p: This is the node for 'no'.
124+~[
125+ [ g=[n=%p a=~]
126+ c=[i=[g=[n=%$ a=~[[n=%$ v="This is the node for 'no'."]]] c=~] t=~]
127+ ]
128+]
129+```
130+
131+;=
132+ ;h3
133+ ;div(id "micmic"): ;; "micmic"
134+ ==
135+==
136+
137+`[%mcmc p=spec q=hoon]`: normalize with a mold, asserting fixpoint.
138+
139+##### Expands to
140+
141+```
142+=+ a=(p q)
143+?> =(`*`a `*`q)
144+a
145+```
146+
147+> Note: the expansion implementation is hygienic -- it doesn't actually add the `a` face to the subject.
148+
149+##### Syntax
150+
151+Regular: *2-fixed*.
152+
153+##### Examples
154+
155+Fails because of auras:
156+
157+```
158+~zod:dojo> ^-(tape ~[97 98 99])
159+! nest-fail
160+! exit
161+```
162+
163+Succeeds because molds don't care about auras:
164+
165+```
166+~zod:dojo> ;;(tape ~[97 98 99])
167+"abc"
168+```
169+
170+Fails because not a fixpoint:
171+
172+```
173+~zod:dojo> ;;(tape [50 51 52])
174+! exit
175+```
176+
177+;=
178+ ;h3
179+ ;div(id "micnet"): ;/ "micnet"
180+ ==
181+==
182+
183+`[%mcnt p=hoon]`: tape as XML element.
184+
185+##### Expands to
186+
187+```
188+~[%$ ~[%$ 'p']]
189+```
190+
191+##### Examples
192+
193+```
194+~zod/try=> :/"foo"
195+[[%~. [%~. "foo] ~] ~]
196+```
197+
198+;=
199+ ;h3
200+ ;div(id "micsig"): ;~ "micsig"
201+ ==
202+==
203+
204+`[%mcsg p=hoon q=(list hoon)]`: glue a pipeline together with a
205+product-sample adapter.
206+
207+##### Produces
208+
209+The gates in `q` are composed together using the gate `p` as an intermediate function, which transforms a `q` product and a `q` gate into a `q` sample.
210+
211+##### Expands to
212+
213+*Note: these are structurally correct, but elide some type-system complexity.*
214+
215+`;~(a b)` reduces to `b`.
216+
217+`;~(a b c)` expands to
218+
219+```
220+|= arg=*
221+(a (b arg) c(+6 arg))
222+```
223+
224+`;~(a b c d)` expands to
225+
226+```
227+|= arg=*
228+%+ a (b arg)
229+=+ arg=arg
230+|. (a (c arg) d(+6 arg))
231+```
232+
233+##### Compiler macro
234+
235+```
236+?~ q !!
237+|-
238+?~ t.q i.q
239+=/ a $(q t.q)
240+=/ b i.q
241+=/ c ,.+6.b
242+|. (p (b c) a(,.+6 c))
243+```
244+
245+##### Discussion
246+
247+Apparently `;~` is a "Kleisli arrow." It's also
248+a close cousin of the infamous "monad." Don't let that bother
249+you. Hoon doesn't know anything about category theory,
250+so you don't need to either.
251+
252+`;~` is often used in parsers, but is not only for parsers.
253+
254+This can be thought of as user-defined function composition; instead of simply
255+nesting the gates in `q`, each is passed individually to `p` with the product
256+of the previous gate, allowing arbitrary filtering, transformation, or
257+conditional application.
258+
259+##### Syntax
260+
261+Regular: *1-fixed*, then *running*.
262+
263+##### Examples
264+
265+A simple "parser." `trip` converts a `cord` (atomic string) to
266+a `tape` (linked string).
267+
268+```
269+~zod:dojo> =cmp |=([a=tape b=$-(char tape)] `tape`?~(a ~ (weld (b i.a) t.a)))
270+~zod:dojo> ;~(cmp trip)
271+<1.zje {a/@ <409.yxa 110.lxv 1.ztu $151>}>
272+~zod:dojo> (;~(cmp trip) 'a')
273+"a"
274+```
275+
276+With just one gate in the pipeline `q`, the glue `p` is unused:
277+
278+```
279+~zod:dojo> (;~(cmp trip |=(a=@ ~[a a])) 'a')
280+"aa"
281+~zod:dojo> (;~(cmp trip |=(a=@ ~[a a])) '')
282+""
283+```
284+
285+But for multiple gates, we need it to connect the pipeline:
286+
287+```
288+~zod:dojo> (;~(cmp trip ;~(cmp |=(a=@ ~[a a]) |=(a=@ <(dec a)>))) 'b')
289+"97b"
290+~zod:dojo> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) 'b')
291+"97b"
292+~zod:dojo> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) '')
293+""
294+~zod:dojo> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) 'a')
295+"96a"
296+~zod:dojo> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) 'acd')
297+"96acd"
298+```
299+
300+;=
301+ ;h3
302+ ;div(id "mictar"): ;* "mictar"
303+ ==
304+==
305+
306+make a list of XML nodes from complex Hoon expression (Sail)
307+
308+##### Produces
309+
310+A `marl`, i.e., a list of `manx`. A `manx` is a noun that represents a single XML node.
311+
312+##### Syntax
313+
314+*1-fixed*
315+
316+```
317+;* p=hoon
318+```
319+
320+`p` is a Hoon expression that produces a `marl`.
321+
322+##### Discussion
323+
324+`;*` is a Sail rune. Sail is a part of Hoon used for creating and operating on nouns that represent XML nodes. With the appropriate rendering pipeline, a Sail document can be used to generate a static website. See the [Sail tutorial](/docs/learn/arvo/arvo-internals/sail).
325+
326+If you need a complex Hoon expression to produce a `marl`, use the `;*` rune. Often this rune is used with an expression, `p`, that includes one or more `;=` subexpressions.
327+
328+(See also [`;=`](#mictis).)
329+
330+##### Examples
331+
332+```
333+> ;* ?: (gth 3 2)
334+ ;= ;p: This is node 1 of 'yes'.
335+ ;p: This is node 2 of 'yes'.
336+ ==
337+ ;= ;p: This is node 1 of 'no'.
338+ ;p: This is node 2 of 'no'.
339+ ==
340+[ [[%p ~] [[%$ [%$ "This is node 1 of 'yes'."] ~] ~] ~]
341+ [[[%p ~] [[%$ [%$ "This is node 2 of 'yes'."] ~] ~] ~] ~]
342+]
343+
344+> ;* ?: (gth 2 3)
345+ ;= ;p: This is node 1 of 'yes'.
346+ ;p: This is node 2 of 'yes'.
347+ ==
348+ ;= ;p: This is node 1 of 'no'.
349+ ;p: This is node 2 of 'no'.
350+ ==
351+[ [[%p ~] [[%$ [%$ "This is node 1 of 'no'."] ~] ~] ~]
352+ [[[%p ~] [[%$ [%$ "This is node 2 of 'no'."] ~] ~] ~] ~]
353+]
354+```
355+
356+;=
357+ ;h3
358+ ;div(id "mictis"): ;= "mictis"
359+ ==
360+==
361+
362+make a list of XML nodes (Sail)
363+
364+##### Produces
365+
366+A `marl`, i.e., a list of `manx`. A `manx` is a noun that represents a single XML node.
367+
368+##### Syntax
369+
370+*running*
371+
372+```
373+;= p=hoon q=hoon ... z=hoon ==
374+```
375+
376+`p`-`z` are Hoon expressions, each of which poduces a `manx`.
377+
378+##### Discussion
379+
380+`;=` is a Sail rune. Sail is a part of Hoon used for creating and operating on nouns that represent XML nodes. With the appropriate rendering pipeline, a Sail document can be used to generate a static website. See the [Sail tutorial](/docs/learn/arvo/arvo-internals/sail).
381+
382+In Sail a single XML node is represented by a `manx`. A single `<p>` node `manx` can be produced in the following way:
383+
384+```
385+> ;p: This will be rendered as an XML node.
386+[[%p ~] [[%$ [%$ "This will be rendered as an XML node."] ~] ~] ~]
387+```
388+
389+Sometimes what is needed is a `marl`, i.e., a list of `manx`. To convert a series of `manx` nodes to a `marl`, use the `;=` rune.
390+
391+(See also [`;*`](#mictar).)
392+
393+##### Examples
394+
395+```
396+> ;= ;p: This is the first node.
397+ ;p: This is the second.
398+ ;p: Here is the last one.
399+ ==
400+[ [[%p ~] [[%$ [%$ "This is the first node."] ~] ~] ~]
401+ [[%p ~] [[%$ [%$ "This is the second."] ~] ~] ~]
402+ [[%p ~] [[%$ [%$ "Here is the last one."] ~] ~] ~]
403+ ~
404+]
405+```
reference/hoon-expressions/rune/mic/col.udondeleted−56
@@ -1,56 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'1'
4− title/';: "miccol"'
5− ==
6−;>
7−
8−# `;: "miccol"`
9−
10−`[%mccl p=hoon q=(list hoon)]`: call a binary function as an n-ary function.
11−
12−## Expands to
13−
14−*Pseudocode*: `a`, `b`, `c`, ... as elements of `q`:
15−
16−Regular form:
17−
18−```
19−%-(p a %-(p b %-(p c ...)))
20−```
21−
22−Irregular form:
23−
24−```
25−(p a (p b (p c ...)))
26−```
27−
28−### Compiler macro
29−
30−```
31−|-
32−?~ q !!
33−?~ t.q !!
34−?~ t.t.q
35− (p i.q i.t.q)
36−(p i.q $(q t.q))
37−```
38−
39−## Syntax
40−
41−Regular: *1-fixed*, then *running*.
42−
43−Irregular: `:(add a b c)` is `;:(add a b c)`.
44−
45−## Examples
46−
47−```
48−~zod:dojo> (add 3 (add 4 5))
49−12
50−
51−~zod:dojo> ;:(add 3 4 5)
52−12
53−
54−~zod:dojo> :(add 3 4 5)
55−12
56−```
reference/hoon-expressions/rune/mic/lus.udondeleted−65
@@ -1,65 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'5'
4− title/';+ "miclus"'
5− ==
6−;>
7−
8−# `;+ "miclus"`
9−
10−make a single XML node (Sail)
11−
12−## Produces
13−
14−A `marl`, i.e., a list of `manx`. A `manx` is a noun that represents a single XML node.
15−
16−## Syntax
17−
18−*1-fixed*
19−
20−```
21−;+ p=hoon
22−```
23−
24−`p` is a Hoon expression that produces a `manx`.
25−
26−## Discussion
27−
28−tl;dr -- `;+` converts a `manx` to a `marl`.
29−
30−`;+` is a Sail rune. Sail is a part of Hoon used for creating and operating on nouns that represent XML nodes. With the appropriate rendering pipeline, a Sail document can be used to generate a static website. See the [Sail tutorial](../../../../tutorials/sail).
31−
32−In Sail a single XML node is represented by a `manx`. A single `<p>` node `manx` can be produced in the following way:
33−
34−```
35−> ;p: This will be rendered as an XML node.
36−[[%p ~] [[%$ [%$ "This will be rendered as an XML node."] ~] ~] ~]
37−```
38−
39−Sometimes what is needed is a `marl`, i.e., a list of `manx`. To convert a single `manx` to a `marl`, use the `;+` rune.
40−
41−One interesting thing about Sail is that it allows you to use complex Hoon expressions to choose from among several nodes to render. The `;+` rune can take such a complex expression.
42−
43−## Examples
44−
45−```
46−> ^- marl
47− ;+ ?: (gth 3 2)
48− ;p: This is the node for 'yes'.
49− ;p: This is the node for 'no'.
50−~[
51− [ g=[n=%p a=~]
52− c=[i=[g=[n=%$ a=~[[n=%$ v="This is the node for 'yes'."]]] c=~] t=~]
53− ]
54−]
55−
56−> ^- marl
57− ;+ ?: (gth 2 3)
58− ;p: This is the node for 'yes'.
59− ;p: This is the node for 'no'.
60−~[
61− [ g=[n=%p a=~]
62− c=[i=[g=[n=%$ a=~[[n=%$ v="This is the node for 'no'."]]] c=~] t=~]
63− ]
64−]
65−```
reference/hoon-expressions/rune/mic/mic.udondeleted−48
@@ -1,48 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'3'
4− title/';; "micmic"'
5− ==
6−;>
7−
8−# `;; "micmic"`
9−
10−`[%mcmc p=spec q=hoon]`: normalize with a mold, asserting fixpoint.
11−
12−## Expands to
13−
14−```
15−=+ a=(p q)
16−?> =(`*`a `*`q)
17−a
18−```
19−
20−> Note: the expansion implementation is hygienic -- it doesn't actually add the `a` face to the subject.
21−
22−## Syntax
23−
24−Regular: *2-fixed*.
25−
26−## Examples
27−
28−Fails because of auras:
29−
30−```
31−~zod:dojo> ^-(tape ~[97 98 99])
32−! nest-fail
33−! exit
34−```
35−
36−Succeeds because molds don't care about auras:
37−
38−```
39−~zod:dojo> ;;(tape ~[97 98 99])
40−"abc"
41−```
42−
43−Fails because not a fixpoint:
44−
45−```
46−~zod:dojo> ;;(tape [50 51 52])
47−! exit
48−```
reference/hoon-expressions/rune/mic/net.udondeleted−23
@@ -1,23 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'4'
4− title/';/ "micnet"'
5− ==
6−;>
7−
8−# `;/ "micnet"`
9−
10−`[%mcnt p=hoon]`: tape as XML element.
11−
12−## Expands to
13−
14−```
15−~[%$ ~[%$ 'p']]
16−```
17−
18−## Examples
19−
20−```
21−~zod/try=> :/"foo"
22−[[%~. [%~. "foo] ~] ~]
23−```
reference/hoon-expressions/rune/mic/sig.udondeleted−104
@@ -1,104 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'2'
4− title/';~ "micsig"'
5− ==
6−;>
7−
8−# `;~ "micsig"`
9−
10−`[%mcsg p=hoon q=(list hoon)]`: glue a pipeline together with a
11−product-sample adapter.
12−
13−## Produces
14−
15−The gates in `q` are composed together using the gate `p` as an intermediate function, which transforms a `q` product and a `q` gate into a `q` sample.
16−
17−## Expands to
18−
19−*Note: these are structurally correct, but elide some type-system complexity.*
20−
21−`;~(a b)` reduces to `b`.
22−
23−`;~(a b c)` expands to
24−
25−```
26−|= arg=*
27−(a (b arg) c(+6 arg))
28−```
29−
30−`;~(a b c d)` expands to
31−
32−```
33−|= arg=*
34−%+ a (b arg)
35−=+ arg=arg
36−|. (a (c arg) d(+6 arg))
37−```
38−
39−### Compiler macro
40−
41−```
42−?~ q !!
43−|-
44−?~ t.q i.q
45−=/ a $(q t.q)
46−=/ b i.q
47−=/ c ,.+6.b
48−|. (p (b c) a(,.+6 c))
49−```
50−
51−## Discussion
52−
53−Apparently `;~` is a "Kleisli arrow." It's also
54−a close cousin of the infamous "monad." Don't let that bother
55−you. Hoon doesn't know anything about category theory,
56−so you don't need to either.
57−
58−`;~` is often used in parsers, but is not only for parsers.
59−
60−This can be thought of as user-defined function composition; instead of simply
61−nesting the gates in `q`, each is passed individually to `p` with the product
62−of the previous gate, allowing arbitrary filtering, transformation, or
63−conditional application.
64−
65−## Syntax
66−
67−Regular: *1-fixed*, then *running*.
68−
69−## Examples
70−
71−A simple "parser." `trip` converts a `cord` (atomic string) to
72−a `tape` (linked string).
73−
74−```
75−~zod:dojo> =cmp |=([a=tape b=$-(char tape)] `tape`?~(a ~ (weld (b i.a) t.a)))
76−~zod:dojo> ;~(cmp trip)
77−<1.zje {a/@ <409.yxa 110.lxv 1.ztu $151>}>
78−~zod:dojo> (;~(cmp trip) 'a')
79−"a"
80−```
81−
82−With just one gate in the pipeline `q`, the glue `p` is unused:
83−
84−```
85−~zod:dojo> (;~(cmp trip |=(a=@ ~[a a])) 'a')
86−"aa"
87−~zod:dojo> (;~(cmp trip |=(a=@ ~[a a])) '')
88−""
89−```
90−
91−But for multiple gates, we need it to connect the pipeline:
92−
93−```
94−~zod:dojo> (;~(cmp trip ;~(cmp |=(a=@ ~[a a]) |=(a=@ <(dec a)>))) 'b')
95−"97b"
96−~zod:dojo> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) 'b')
97−"97b"
98−~zod:dojo> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) '')
99−""
100−~zod:dojo> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) 'a')
101−"96a"
102−~zod:dojo> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) 'acd')
103−"96acd"
104−```
reference/hoon-expressions/rune/mic/tar.udondeleted−58
@@ -1,58 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'7'
4− title/';* "mictar"'
5− ==
6−;>
7−
8−# `;* "mictar"`
9−
10−make a list of XML nodes from complex Hoon expression (Sail)
11−
12−## Produces
13−
14−A `marl`, i.e., a list of `manx`. A `manx` is a noun that represents a single XML node.
15−
16−## Syntax
17−
18−*1-fixed*
19−
20−```
21−;* p=hoon
22−```
23−
24−`p` is a Hoon expression that produces a `marl`.
25−
26−## Discussion
27−
28−`;*` is a Sail rune. Sail is a part of Hoon used for creating and operating on nouns that represent XML nodes. With the appropriate rendering pipeline, a Sail document can be used to generate a static website. See the [Sail tutorial](../../../../tutorials/sail).
29−
30−If you need a complex Hoon expression to produce a `marl`, use the `;*` rune. Often this rune is used with an expression, `p`, that includes one or more `;=` subexpressions.
31−
32−(See also [;=](../tis).)
33−
34−## Examples
35−
36−```
37−> ;* ?: (gth 3 2)
38− ;= ;p: This is node 1 of 'yes'.
39− ;p: This is node 2 of 'yes'.
40− ==
41− ;= ;p: This is node 1 of 'no'.
42− ;p: This is node 2 of 'no'.
43− ==
44−[ [[%p ~] [[%$ [%$ "This is node 1 of 'yes'."] ~] ~] ~]
45− [[[%p ~] [[%$ [%$ "This is node 2 of 'yes'."] ~] ~] ~] ~]
46−]
47−
48−> ;* ?: (gth 2 3)
49− ;= ;p: This is node 1 of 'yes'.
50− ;p: This is node 2 of 'yes'.
51− ==
52− ;= ;p: This is node 1 of 'no'.
53− ;p: This is node 2 of 'no'.
54− ==
55−[ [[%p ~] [[%$ [%$ "This is node 1 of 'no'."] ~] ~] ~]
56− [[[%p ~] [[%$ [%$ "This is node 2 of 'no'."] ~] ~] ~] ~]
57−]
58−```
reference/hoon-expressions/rune/mic/tis.udondeleted−53
@@ -1,53 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'6'
4− title/';= "mictis"'
5− ==
6−;>
7−
8−# `;= "mictis"`
9−
10−make a list of XML nodes (Sail)
11−
12−## Produces
13−
14−A `marl`, i.e., a list of `manx`. A `manx` is a noun that represents a single XML node.
15−
16−## Syntax
17−
18−*running*
19−
20−```
21−;= p=hoon q=hoon ... z=hoon ==
22−```
23−
24−`p`-`z` are Hoon expressions, each of which poduces a `manx`.
25−
26−## Discussion
27−
28−`;=` is a Sail rune. Sail is a part of Hoon used for creating and operating on nouns that represent XML nodes. With the appropriate rendering pipeline, a Sail document can be used to generate a static website. See the [Sail tutorial](../../../../tutorials/sail).
29−
30−In Sail a single XML node is represented by a `manx`. A single `<p>` node `manx` can be produced in the following way:
31−
32−```
33−> ;p: This will be rendered as an XML node.
34−[[%p ~] [[%$ [%$ "This will be rendered as an XML node."] ~] ~] ~]
35−```
36−
37−Sometimes what is needed is a `marl`, i.e., a list of `manx`. To convert a series of `manx` nodes to a `marl`, use the `;=` rune.
38−
39−(See also [`;*`](../tar).)
40−
41−## Examples
42−
43−```
44−> ;= ;p: This is the first node.
45− ;p: This is the second.
46− ;p: Here is the last one.
47− ==
48−[ [[%p ~] [[%$ [%$ "This is the first node."] ~] ~] ~]
49− [[%p ~] [[%$ [%$ "This is the second."] ~] ~] ~]
50− [[%p ~] [[%$ [%$ "Here is the last one."] ~] ~] ~]
51− ~
52−]
53−```
reference/hoon-expressions/rune/sig.udon+488−1
@@ -11,4 +11,491 @@ Runes that use Nock `11` to pass non-semantic info to the interpreter.
11
11
12## Runes
12## Runes
13
13
14−;list(datapreview "true", classname "runes");
14+;=
15+ ;h3
16+ ;div(id "sigban"): ~> "sigban"
17+ ==
18+==
19+
20+`[%sgbn p=$@(term [p=term q=hoon]) q=hoon]`: raw hint, applied
21+to computation.
22+
23+##### Expands to
24+
25+`q`.
26+
27+##### Syntax
28+
29+Regular: *2-fixed*. For the dynamic form, write `%term.hoon`.
30+
31+##### Discussion
32+
33+Hoon has no way of telling what hints are used and what aren't.
34+Hints are all conventions at the interpreter level.
35+
36+##### Examples
37+
38+```
39+~zod:dojo> ~>(%a 42)
40+42
41+```
42+
43+Running the compiler:
44+
45+```
46+~zod:dojo> (make '~>(%a 42)')
47+[%10 p=97 q=[%1 p=42]]
48+
49+~zod:dojo> (make '~>(%a.+(2) 42)')
50+[%10 p=[p=97 q=[%4 p=[%1 p=2]]] q=[%1 p=42]]
51+```
52+
53+;=
54+ ;h3
55+ ;div(id "sigbar"): ~| "sigbar"
56+ ==
57+==
58+
59+
60+`[%sgbr p=hoon q=hoon]`: tracing printf.
61+
62+##### Expands to
63+
64+`q`.
65+
66+##### Convention
67+
68+Prettyprints `p` in stack trace if `q` crashes.
69+
70+##### Syntax
71+
72+Regular: *2-fixed*.
73+
74+##### Examples
75+
76+```
77+~zod:dojo> ~|('sample error message' !!)
78+'sample error message'
79+ford: build failed
80+
81+~zod:dojo> ~| 'sample error message'
82+ !!
83+'sample error message'
84+ford: build failed
85+```
86+
87+;=
88+ ;h3
89+ ;div(id "sigbus"): ~$ "sigbus"
90+ ==
91+==
92+
93+`[%sgbs p=term q=hoon]`: profiling hit counter.
94+
95+##### Expands to
96+
97+`q`.
98+
99+##### Convention
100+
101+If profiling is on, adds 1 to the hit counter for `p`.
102+
103+##### Syntax
104+
105+Regular: *2-fixed*.
106+
107+##### Examples
108+
109+```
110+~zod:dojo> ~$(%foo 3)
111+3
112+```
113+
114+;=
115+ ;h3
116+ ;div(id "sigcab"): ~_ "sigcab"
117+ ==
118+==
119+
120+`[%sgcb p=hoon q=hoon]`: user-formatted tracing printf.
121+
122+##### Expands to
123+
124+`q`.
125+
126+##### Convention
127+
128+Shows `p` in stacktrace if `q` crashes.
129+
130+##### Discussion
131+
132+`p` must produce a `tank` (prettyprint source).
133+
134+##### Examples
135+
136+```
137+~zod:dojo> ~_([%leaf "sample error message"] !!)
138+"sample error message"
139+ford: build failed
140+
141+~zod:dojo> ~_ [%leaf "sample error message"]
142+ !!
143+"sample error message"
144+ford: build failed
145+```
146+
147+;=
148+ ;h3
149+ ;div(id "cigcen"): ~% "sigcen"
150+ ==
151+==
152+
153+`[%sgcn p=term q=wing r=(list [term hoon]) s=hoon]`: jet registration.
154+
155+##### Expands to
156+
157+`s`.
158+
159+##### Convention
160+
161+Register a core with name `p`, with parent at leg `q`, exporting
162+the named formulas `r`, constructed by `s`.
163+
164+##### Syntax
165+
166+Regular: *4-fixed*. For `r`, use `~` if empty. Otherwise, *jogging*
167+between opening and closing `==`.
168+
169+##### Discussion
170+
171+`~%` is for registering cores. A registered core declares its
172+formal identity to the interpreter, which may or may not be able
173+to recognize and/or accelerate it.
174+
175+Registered cores are organized in a containment hierarchy.
176+The parent core is at any leg within the child core. When we
177+register a core, we state the leg to its parent, in the form of
178+wing `q`. We assume the parent is already registered -- as it
179+must be, if (a) we registered it on creation, (b) the child was
180+created by an arm defined on the parent.
181+
182+(Cores are actually managed by their formula/battery. Any
183+function call will create a new core with a new sample, but
184+batteries are constant. But it is not sufficient to match the
185+battery -- matching the semantics constrains the payload as well,
186+since the semantics of a battery may depend on any parent core
187+and/or payload constant.)
188+
189+The purpose of registration is always performance-related. It
190+may involve (a) a special-purpose optimizer or "jet", written
191+for a specific core and checked with a Merkle hash; (b) a
192+general-purpose hotspot optimizer or "JIT"; or (c) merely a
193+hotspot declaration for profiling.
194+
195+As always with hints, the programmer has no idea which of (a),
196+(b), and (c) will be applied. Use `~%`
197+indiscriminately on all hotspots, bottlenecks, etc, real or
198+suspected.
199+
200+The list `r` is a way for the Hoon programmer to help jet
201+implementors with named Nock formulas that act on the core.
202+In complex systems, jet implementations are often partial and
203+want to call back into userspace.
204+
205+The child core contains the parent, of course. When we register
206+a core, we state the leg to its parent, in the form of wing `q`.
207+We assume that the parent -- any core within the payload -- is
208+already registered.
209+
210+`p` is the name of this core within its parent; `q` is a the leg
211+
212+Registers a jet in core `s` so that it can be called when that code is run.
213+
214+Regular form: *4-fixed*
215+
216+##### Examples
217+
218+Here's the AES
219+
220+```
221+ ++ aesc :: AES-256
222+ ~% %aesc + ~
223+ |%
224+ ++ en :: ECB enc
225+ ~/ %en
226+ |= [a=@I b=@H] ^- @uxH
227+ =+ ahem
228+ (be & (ex a) b)
229+ ++ de :: ECB dec
230+ ~/ %de
231+ |= [a=@I b=@H] ^- @uxH
232+ =+ ahem
233+ (be | (ix (ex a)) b)
234+ --
235+```
236+
237+Here we label the entire `++aesc` core for optimization. You can see the
238+jet in `jets/e/aesc.c`.
239+
240+
241+;=
242+ ;h3
243+ ;div(id "sigled"): ~< "sigled"
244+ ==
245+==
246+
247+
248+`[%sgld p=$@(term [p=term q=hoon]) q=hoon]`: raw hint, applied to
249+product.
250+
251+##### Expands to
252+
253+`q`.
254+
255+##### Syntax
256+
257+Regular: *2-fixed*. For the dynamic form, write `%term.hoon`.
258+
259+##### Discussion
260+
261+`~<` is only used for jet hints ([`~/`](#sigfas)
262+and [`~%`](#sigcen)) at the moment; we are not telling the
263+interpreter something about the computation we're about to perform, but
264+rather about its product.
265+
266+##### Examples
267+
268+```
269+~zod:dojo> (make '~<(%a 42)')
270+[%7 p=[%1 p=42] q=[%10 p=97 q=[%0 p=1]]]
271+~zod:dojo> (make '~<(%a.+(.) 42)')
272+[%7 p=[%1 p=42] q=[%10 p=[p=97 q=[%4 p=[%0 p=1]]] q=[%0 p=1]]]
273+```
274+
275+;=
276+ ;h3
277+ ;div(id "siglus"): ~+ "siglus"
278+ ==
279+==
280+
281+`[%sgls p=hoon]`: cache a computation.
282+
283+##### Expands to
284+
285+`p`.
286+
287+##### Convention
288+
289+Caches the formula and subject of `p` in a local cache (generally
290+transient in the current event).
291+
292+##### Syntax
293+
294+Regular: *1-fixed*.
295+
296+##### Examples
297+
298+This may pause for a second:
299+
300+```
301+~zod:dojo> %.(25 |=(a=@ ?:((lth a 2) 1 (add $(a (sub a 2)) $(a (dec a))))))
302+121.393
303+```
304+
305+This may make you want to press `ctrl-c`:
306+
307+```
308+~zod:dojo> %.(30 |=(a=@ ?:((lth a 2) 1 (add $(a (sub a 2)) $(a (dec a))))))
309+1.346.269
310+```
311+
312+This should work fine:
313+
314+```
315+~zod:dojo> %.(100 |=(a=@ ~+(?:((lth a 2) 1 (add $(a (sub a 2)) $(a (dec a)))))))
316+573.147.844.013.817.084.101
317+```
318+
319+;=
320+ ;h3
321+ ;div(id "signet"): ~/ "signet"
322+ ==
323+==
324+
325+`[%sgnt p=term q=hoon]`: jet registration for gate with
326+registered context.
327+
328+##### Expands to
329+
330+```
331+~%(p +7 ~ q)
332+```
333+
334+##### Syntax
335+
336+Regular: *2-fixed*.
337+
338+##### Examples
339+
340+From the kernel:
341+```
342+++ add
343+ ~/ %add
344+ |= [a=@ b=@]
345+ ^- @
346+ ?: =(0 a) b
347+ $(a (dec a), b +(b))
348+```
349+
350+;=
351+ ;h3
352+ ;div(id "sigpad"): ~& "sigpad"
353+ ==
354+==
355+
356+`[%sgpd p=hoon q=hoon]`: debugging printf.
357+
358+##### Expands to
359+
360+`q`.
361+
362+##### Product
363+
364+Pretty-prints `p` on the console before computing `q`.
365+
366+##### Discussion
367+
368+This rune has no semantic effect beyond the Hoon expression `q`. It's used solely to create a side-effect: printing the value of `p` to the console.
369+
370+It's most useful for debugging programs.
371+
372+##### Syntax
373+
374+Regular: *2-fixed*.
375+
376+##### Examples
377+
378+```
379+~zod:dojo> ~&('halp' ~)
380+'halp'
381+~
382+
383+~zod:dojo> ~& 'halp'
384+ ~
385+'halp'
386+~
387+```
388+
389+;=
390+ ;h3
391+ ;div(id "sigtis"): ~= "sigtis"
392+ ==
393+==
394+
395+`[%sgts p=hoon q=hoon]`: detect duplicate.
396+
397+##### Expands to
398+
399+`q`.
400+
401+##### Convention
402+
403+If `p` equals `q`, produce `p` instead of `q`.
404+
405+##### Discussion
406+
407+Duplicate nouns are especially bad news in Hoon, because comparing them
408+takes O(n) time. Use `~=` to avoid this inefficiency.
409+
410+##### Examples
411+
412+This code traverses a tree and replaces all instances of `32` with
413+`320`:
414+
415+```
416+~zod:dojo> =foo |= a=(tree)
417+ ?~(a ~ ~=(a [?:(=(n.a 32) 320 n.a) $(a l.a) $(a r.a)]))
418+
419+~zod:dojo> (foo 32 ~ ~)
420+[320 ~ ~]
421+```
422+
423+Without `~=`, it would build a copy of a completely unchanged tree. Sad!
424+
425+;=
426+ ;h3
427+ ;div(id "sigwut"): ~? "sigwut"
428+ ==
429+==
430+
431+`[%sgwt p=hoon q=hoon r=hoon]`: conditional debug printf.
432+
433+##### Expands to
434+
435+`r`.
436+
437+##### Convention
438+
439+If `p` is true, prettyprints `q` on the console before computing `r`.
440+
441+##### Syntax
442+
443+Regular: *4-fixed*.
444+
445+##### Examples
446+
447+```
448+~zod:dojo> ~?((gth 1 2) 'oops' ~)
449+~
450+
451+~zod:dojo> ~?((gth 1 0) 'oops' ~)
452+'oops'
453+~
454+
455+~zod:dojo> ~? (gth 1 2)
456+ 'oops'
457+ ~
458+~
459+
460+~zod:dojo> ~? (gth 1 0)
461+ 'oops'
462+ ~
463+'oops'
464+~
465+```
466+
467+;=
468+ ;h3
469+ ;div(id "sigzap"): ~! "sigzap"
470+ ==
471+==
472+
473+`[%sgzp p=hoon q=hoon]`: print type on compilation fail.
474+
475+##### Expands to
476+
477+`q`.
478+
479+##### Convention
480+
481+If compilation of `q` fails, prints the type of `p` in the trace.
482+
483+##### Syntax
484+
485+Regular: *2-fixed*.
486+
487+##### Examples
488+
489+```
490+~zod:dojo> a
491+! -find.a
492+
493+~zod:dojo> ~!('foo' a)
494+! @t
495+! find.a
496+
497+~zod:dojo> ~! 'foo'
498+ a
499+! @t
500+! find.a
501+```
reference/hoon-expressions/rune/sig/ban.udondeleted−41
@@ -1,41 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'3'
4− title/'~> "sigban"'
5− ==
6−;>
7−
8−# `~> "sigban"`
9−
10−`[%sgbn p=$@(term [p=term q=hoon]) q=hoon]`: raw hint, applied
11−to computation.
12−
13−## Expands to
14−
15−`q`.
16−
17−## Syntax
18−
19−Regular: *2-fixed*. For the dynamic form, write `%term.hoon`.
20−
21−## Discussion
22−
23−Hoon has no way of telling what hints are used and what aren't.
24−Hints are all conventions at the interpreter level.
25−
26−## Examples
27−
28−```
29−~zod:dojo> ~>(%a 42)
30−42
31−```
32−
33−Running the compiler:
34−
35−```
36−~zod:dojo> (make '~>(%a 42)')
37−[%10 p=97 q=[%1 p=42]]
38−
39−~zod:dojo> (make '~>(%a.+(2) 42)')
40−[%10 p=[p=97 q=[%4 p=[%1 p=2]]] q=[%1 p=42]]
41−```
reference/hoon-expressions/rune/sig/bar.udondeleted−35
@@ -1,35 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'7'
4− title/'~| "sigbar"'
5− ==
6−;>
7−
8−# `~| "sigbar"`
9−
10−`[%sgbr p=hoon q=hoon]`: tracing printf.
11−
12−## Expands to
13−
14−`q`.
15−
16−## Convention
17−
18−Prettyprints `p` in stack trace if `q` crashes.
19−
20−## Syntax
21−
22−Regular: *2-fixed*.
23−
24−## Examples
25−
26−```
27−~zod:dojo> ~|('sample error message' !!)
28−'sample error message'
29−ford: build failed
30−
31−~zod:dojo> ~| 'sample error message'
32− !!
33−'sample error message'
34−ford: build failed
35−```
reference/hoon-expressions/rune/sig/bus.udondeleted−29
@@ -1,29 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'11'
4− title/'~$ "sigbus"'
5− ==
6−;>
7−
8−# `~$ "sigbus"`
9−
10−`[%sgbs p=term q=hoon]`: profiling hit counter.
11−
12−## Expands to
13−
14−`q`.
15−
16−## Convention
17−
18−If profiling is on, adds 1 to the hit counter for `p`.
19−
20−## Syntax
21−
22−Regular: *2-fixed*.
23−
24−## Examples
25−
26−```
27−~zod:dojo> ~$(%foo 3)
28−3
29−```
reference/hoon-expressions/rune/sig/cab.udondeleted−35
@@ -1,35 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'8'
4− title/'~_ "sigcab"'
5− ==
6−;>
7−
8−# `~_ "sigcab"`
9−
10−`[%sgcb p=hoon q=hoon]`: user-formatted tracing printf.
11−
12−## Expands to
13−
14−`q`.
15−
16−## Convention
17−
18−Shows `p` in stacktrace if `q` crashes.
19−
20−## Discussion
21−
22−`p` must produce a `tank` (prettyprint source).
23−
24−## Examples
25−
26−```
27−~zod:dojo> ~_([%leaf "sample error message"] !!)
28−"sample error message"
29−ford: build failed
30−
31−~zod:dojo> ~_ [%leaf "sample error message"]
32− !!
33−"sample error message"
34−ford: build failed
35−```
reference/hoon-expressions/rune/sig/cen.udondeleted−95
@@ -1,95 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'2'
4− title/'~% "sigcen"'
5− ==
6−;>
7−
8−# `~% "sigcen"`
9−
10−`[%sgcn p=term q=wing r=(list [term hoon]) s=hoon]`: jet registration.
11−
12−## Expands to
13−
14−`s`.
15−
16−## Convention
17−
18−Register a core with name `p`, with parent at leg `q`, exporting
19−the named formulas `r`, constructed by `s`.
20−
21−## Syntax
22−
23−Regular: *4-fixed*. For `r`, use `~` if empty. Otherwise, *jogging*
24−between opening and closing `==`.
25−
26−## Discussion
27−
28−`~%` is for registering cores. A registered core declares its
29−formal identity to the interpreter, which may or may not be able
30−to recognize and/or accelerate it.
31−
32−Registered cores are organized in a containment hierarchy.
33−The parent core is at any leg within the child core. When we
34−register a core, we state the leg to its parent, in the form of
35−wing `q`. We assume the parent is already registered -- as it
36−must be, if (a) we registered it on creation, (b) the child was
37−created by an arm defined on the parent.
38−
39−(Cores are actually managed by their formula/battery. Any
40−function call will create a new core with a new sample, but
41−batteries are constant. But it is not sufficient to match the
42−battery -- matching the semantics constrains the payload as well,
43−since the semantics of a battery may depend on any parent core
44−and/or payload constant.)
45−
46−The purpose of registration is always performance-related. It
47−may involve (a) a special-purpose optimizer or "jet", written
48−for a specific core and checked with a Merkle hash; (b) a
49−general-purpose hotspot optimizer or "JIT"; or (c) merely a
50−hotspot declaration for profiling.
51−
52−As always with hints, the programmer has no idea which of (a),
53−(b), and (c) will be applied. Use `~%`
54−indiscriminately on all hotspots, bottlenecks, etc, real or
55−suspected.
56−
57−The list `r` is a way for the Hoon programmer to help jet
58−implementors with named Nock formulas that act on the core.
59−In complex systems, jet implementations are often partial and
60−want to call back into userspace.
61−
62−The child core contains the parent, of course. When we register
63−a core, we state the leg to its parent, in the form of wing `q`.
64−We assume that the parent -- any core within the payload -- is
65−already registered.
66−
67−`p` is the name of this core within its parent; `q` is a the leg
68−
69−Registers a jet in core `s` so that it can be called when that code is run.
70−
71−Regular form: *4-fixed*
72−
73−## Examples
74−
75−Here's the AES
76−
77−```
78− ++ aesc :: AES-256
79− ~% %aesc + ~
80− |%
81− ++ en :: ECB enc
82− ~/ %en
83− |= [a=@I b=@H] ^- @uxH
84− =+ ahem
85− (be & (ex a) b)
86− ++ de :: ECB dec
87− ~/ %de
88− |= [a=@I b=@H] ^- @uxH
89− =+ ahem
90− (be | (ix (ex a)) b)
91− --
92−```
93−
94−Here we label the entire `++aesc` core for optimization. You can see the
95−jet in `jets/e/aesc.c`.
reference/hoon-expressions/rune/sig/led.udondeleted−35
@@ -1,35 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'4'
4− title/'~< "sigled"'
5− ==
6−;>
7−
8−# `~< "sigled"`
9−
10−`[%sgld p=$@(term [p=term q=hoon]) q=hoon]`: raw hint, applied to
11−product.
12−
13−## Expands to
14−
15−`q`.
16−
17−## Syntax
18−
19−Regular: *2-fixed*. For the dynamic form, write `%term.hoon`.
20−
21−## Discussion
22−
23−`~<` is only used for jet hints ([`~/`](../fas/)
24−and [`~%`](../cen/)) at the moment; we are not telling the
25−interpreter something about the computation we're about to perform, but
26−rather about its product.
27−
28−## Examples
29−
30−```
31−~zod:dojo> (make '~<(%a 42)')
32−[%7 p=[%1 p=42] q=[%10 p=97 q=[%0 p=1]]]
33−~zod:dojo> (make '~<(%a.+(.) 42)')
34−[%7 p=[%1 p=42] q=[%10 p=[p=97 q=[%4 p=[%0 p=1]]] q=[%0 p=1]]]
35−```
reference/hoon-expressions/rune/sig/lus.udondeleted−46
@@ -1,46 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'9'
4− title/'~+ "siglus"'
5− ==
6−;>
7−
8−# `~+ "siglus"`
9−
10−`[%sgls p=hoon]`: cache a computation.
11−
12−## Expands to
13−
14−`p`.
15−
16−## Convention
17−
18−Caches the formula and subject of `p` in a local cache (generally
19−transient in the current event).
20−
21−## Syntax
22−
23−Regular: *1-fixed*.
24−
25−## Examples
26−
27−This may pause for a second:
28−
29−```
30−~zod:dojo> %.(25 |=(a=@ ?:((lth a 2) 1 (add $(a (sub a 2)) $(a (dec a))))))
31−121.393
32−```
33−
34−This may make you want to press `ctrl-c`:
35−
36−```
37−~zod:dojo> %.(30 |=(a=@ ?:((lth a 2) 1 (add $(a (sub a 2)) $(a (dec a))))))
38−1.346.269
39−```
40−
41−This should work fine:
42−
43−```
44−~zod:dojo> %.(100 |=(a=@ ~+(?:((lth a 2) 1 (add $(a (sub a 2)) $(a (dec a)))))))
45−573.147.844.013.817.084.101
46−```
reference/hoon-expressions/rune/sig/net.udondeleted−33
@@ -1,33 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'12'
4− title/'~/ "signet"'
5− ==
6−;>
7−
8−# `~/ "signet"`
9−
10−`[%sgnt p=term q=hoon]`: jet registration for gate with
11−registered context.
12−
13−## Expands to
14−
15−```
16−~%(p +7 ~ q)
17−```
18−
19−## Syntax
20−
21−Regular: *2-fixed*.
22−
23−## Examples
24−
25−From the kernel:
26−```
27−++ add
28− ~/ %add
29− |= [a=@ b=@]
30− ^- @
31− ?: =(0 a) b
32− $(a (dec a), b +(b))
33−```
reference/hoon-expressions/rune/sig/pad.udondeleted−41
@@ -1,41 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'1'
4− title/'~& "sigpad"'
5− ==
6−;>
7−
8−# `~& "sigpad"`
9−
10−`[%sgpd p=hoon q=hoon]`: debugging printf.
11−
12−## Expands to
13−
14−`q`.
15−
16−## Product
17−
18−Pretty-prints `p` on the console before computing `q`.
19−
20−## Discussion
21−
22−This rune has no semantic effect beyond the Hoon expression `q`. It's used solely to create a side-effect: printing the value of `p` to the console.
23−
24−It's most useful for debugging programs.
25−
26−## Syntax
27−
28−Regular: *2-fixed*.
29−
30−## Examples
31−
32−```
33−~zod:dojo> ~&('halp' ~)
34−'halp'
35−~
36−
37−~zod:dojo> ~& 'halp'
38− ~
39−'halp'
40−~
41−```
reference/hoon-expressions/rune/sig/tis.udondeleted−38
@@ -1,38 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'10'
4− title/'~= "sigtis"'
5− ==
6−;>
7−
8−# `~= "sigtis"`
9−
10−`[%sgts p=hoon q=hoon]`: detect duplicate.
11−
12−## Expands to
13−
14−`q`.
15−
16−## Convention
17−
18−If `p` equals `q`, produce `p` instead of `q`.
19−
20−## Discussion
21−
22−Duplicate nouns are especially bad news in Hoon, because comparing them
23−takes O(n) time. Use `~=` to avoid this inefficiency.
24−
25−## Examples
26−
27−This code traverses a tree and replaces all instances of `32` with
28−`320`:
29−
30−```
31−~zod:dojo> =foo |= a=(tree)
32− ?~(a ~ ~=(a [?:(=(n.a 32) 320 n.a) $(a l.a) $(a r.a)]))
33−
34−~zod:dojo> (foo 32 ~ ~)
35−[320 ~ ~]
36−```
37−
38−Without `~=`, it would build a copy of a completely unchanged tree. Sad!
reference/hoon-expressions/rune/sig/wut.udondeleted−44
@@ -1,44 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'5'
4− title/'~? "sigwut"'
5− ==
6−;>
7−
8−# `~? "sigwut"`
9−
10−`[%sgwt p=hoon q=hoon r=hoon]`: conditional debug printf.
11−
12−## Expands to
13−
14−`r`.
15−
16−## Convention
17−
18−If `p` is true, prettyprints `q` on the console before computing `r`.
19−
20−## Syntax
21−
22−Regular: *4-fixed*.
23−
24−## Examples
25−
26−```
27−~zod:dojo> ~?((gth 1 2) 'oops' ~)
28−~
29−
30−~zod:dojo> ~?((gth 1 0) 'oops' ~)
31−'oops'
32−~
33−
34−~zod:dojo> ~? (gth 1 2)
35− 'oops'
36− ~
37−~
38−
39−~zod:dojo> ~? (gth 1 0)
40− 'oops'
41− ~
42−'oops'
43−~
44−```
reference/hoon-expressions/rune/sig/zap.udondeleted−38
@@ -1,38 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'6'
4− title/'~! "sigzap"'
5− ==
6−;>
7−
8−# `~! "sigzap"`
9−
10−`[%sgzp p=hoon q=hoon]`: print type on compilation fail.
11−
12−## Expands to
13−
14−`q`.
15−
16−## Convention
17−
18−If compilation of `q` fails, prints the type of `p` in the trace.
19−
20−## Syntax
21−
22−Regular: *2-fixed*.
23−
24−## Examples
25−
26−```
27−~zod:dojo> a
28−! -find.a
29−
30−~zod:dojo> ~!('foo' a)
31−! @t
32−! find.a
33−
34−~zod:dojo> ~! 'foo'
35− a
36−! @t
37−! find.a
38−```
reference/hoon-expressions/rune/terminators.udon+77−1
@@ -11,4 +11,80 @@ The `--` and `==` are used as terminators: `--` for core expressions, and `==` f
11
11
12## Runes
12## Runes
13
13
14−;list(datapreview "true", classname "runes");
14+;=
15+ ;h3
16+ ;div(id "hephep"): -- "hephep"
17+ ==
18+==
19+
20+##### Syntax
21+
22+The `--` rune is used to indicate the end of a core expression.
23+
24+##### Discussion
25+
26+The `|%`, `|_`, and `|^` runes are used to create cores that can have arbitrarily many arms. When you have defined all the desired arms in a core expression (using the `++`, `+$`, and `+*` runes), use `--` to terminate the expression.
27+
28+##### Examples
29+
30+```
31+> =num |%
32+ ++ two 2
33+ ++ add-two |=(a=@ (add 2 a))
34+ ++ double |=(a=@ (mul 2 a))
35+ --
36+
37+> two.num
38+2
39+
40+> (add-two.num 12)
41+14
42+
43+> (double.num 12)
44+24
45+```
46+
47+;=
48+ ;h3
49+ ;div(id "tistis"): == "tistis"
50+ ==
51+==
52+
53+##### Syntax
54+
55+The `==` rune is used to indicate the end of a 'jogging' or 'running' series of Hoon expressions.
56+
57+##### Discussion
58+
59+Certain runes are used to create expressions that may include arbitrarily many subexpressions. Such expressions are terminated with the `==` rune. For example, the `:*` and `:~` runes are used to create a cell of any length. (The latter is just like the former except that it adds a null value at the end of the cell.) For another example, the `%=` rune used used to make arbitrarily many changes to a given wing value.
60+
61+##### Examples
62+
63+```
64+> :* 2
65+ 3
66+ 4
67+ 5
68+ 6
69+ ==
70+[2 3 4 5 6]
71+
72+> :~ 2
73+ 3
74+ 4
75+ 5
76+ 6
77+ ==
78+[2 3 4 5 6 ~]
79+
80+> =values [a=12 b=14 c=16 d=18 e=20]
81+
82+> %= values
83+ a 13
84+ b 15
85+ c 17
86+ d 19
87+ e 21
88+ ==
89+[a=13 b=15 c=17 d=19 e=21]
90+```
reference/hoon-expressions/rune/terminators/hephep.udondeleted−35
@@ -1,35 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'1'
4− title/'-- "hephep"'
5− ==
6−;>
7−
8−# `-- "hephep"`
9−
10−## Syntax
11−
12−The `--` rune is used to indicate the end of a core expression.
13−
14−## Discussion
15−
16−The `|%`, `|_`, and `|^` runes are used to create cores that can have arbitrarily many arms. When you have defined all the desired arms in a core expression (using the `++`, `+$`, and `+*` runes), use `--` to terminate the expression.
17−
18−## Examples
19−
20−```
21−> =num |%
22− ++ two 2
23− ++ add-two |=(a=@ (add 2 a))
24− ++ double |=(a=@ (mul 2 a))
25− --
26−
27−> two.num
28−2
29−
30−> (add-two.num 12)
31−14
32−
33−> (double.num 12)
34−24
35−```
reference/hoon-expressions/rune/terminators/tistis.udondeleted−47
@@ -1,47 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'2'
4− title/'== "tistis"'
5− ==
6−;>
7−
8−# `== "tistis"`
9−
10−## Syntax
11−
12−The `==` rune is used to indicate the end of a 'jogging' or 'running' series of Hoon expressions.
13−
14−## Discussion
15−
16−Certain runes are used to create expressions that may include arbitrarily many subexpressions. Such expressions are terminated with the `==` rune. For example, the `:*` and `:~` runes are used to create a cell of any length. (The latter is just like the former except that it adds a null value at the end of the cell.) For another example, the `%=` rune used used to make arbitrarily many changes to a given wing value.
17−
18−## Examples
19−
20−```
21−> :* 2
22− 3
23− 4
24− 5
25− 6
26− ==
27−[2 3 4 5 6]
28−
29−> :~ 2
30− 3
31− 4
32− 5
33− 6
34− ==
35−[2 3 4 5 6 ~]
36−
37−> =values [a=12 b=14 c=16 d=18 e=20]
38−
39−> %= values
40− a 13
41− b 15
42− c 17
43− d 19
44− e 21
45− ==
46−[a=13 b=15 c=17 d=19 e=21]
47−```
reference/hoon-expressions/rune/tis.udon+520−1
@@ -27,4 +27,523 @@ different situations. Hence the whole family of `=` runes.
27
27
28## Runes
28## Runes
29
29
30−;list(datapreview "true", classname "runes");
30+;=
31+ ;h3
32+ ;div(id "tisban"): => "tisban"
33+ ==
34+==
35+
36+`[%tsgr p=hoon q=hoon]`: compose two expressions.
37+
38+##### Produces
39+
40+the product of `q`, with the product of `p` taken as the subject.
41+
42+##### Syntax
43+
44+Regular: *2-fixed*.
45+
46+##### Examples
47+
48+```
49+> =>([a=1 b=2 c=3] b)
50+2
51+
52+> =>((add 2 4) [. .])
53+[6 6]
54+```
55+
56+;=
57+ ;h3
58+ ;div(id "tisbar"): =| "tisbar"
59+ ==
60+==
61+
62+
63+`[%tsbr p=spec q=hoon]`: combine a default type value with the subject.
64+
65+##### Expands to
66+
67+```
68+=+(*p q)
69+```
70+
71+##### Syntax
72+
73+Regular: *2-fixed*.
74+
75+##### Discussion
76+
77+The default (or 'bunt') value of `p` is pinned to the head of the subject. Usually `p` includes a name for ease of reference.
78+
79+Speaking more loosely, `=|` usually "declares a variable" which is "uninitialized," presumably because you'll set it in a loop or similar.
80+
81+##### Examples
82+
83+```
84+~zod:dojo> =foo |= a=@
85+ =| b=@
86+ =- :(add a b c)
87+ c=2
88+~zod:dojo> (foo 5)
89+7
90+```
91+
92+;=
93+ ;h3
94+ ;div(id "tisbar"): =: "tisbar"
95+ ==
96+==
97+
98+`[%tscl p=(list (pair wing hoon)) q=hoon]`: change multiple legs in the subject.
99+
100+##### Expands to
101+
102+```
103+=>(%_(. p) q)
104+```
105+
106+##### Syntax
107+
108+Regular: *jogging*, then *1-fixed*.
109+
110+##### Discussion
111+
112+This rune is like `=.`, but for modifying the values of multiple legs of the subject.
113+
114+##### Examples
115+
116+```
117+~zod:dojo> =+ a=[b=1 c=2]
118+ =: c.a 4
119+ b.a 3
120+ ==
121+ a
122+[b=3 c=4]
123+```
124+
125+;=
126+ ;h3
127+ ;div(id "tiscom"): =, "tiscom"
128+ ==
129+==
130+
131+`[%tscm p=hoon q=hoon]`: expose namespace
132+
133+`p` evaluates to a noun with some namespace. From within `q` you may access `p`'s names without a wing path (i.e., you can use face `b` rather than `b.p`). This is especially useful for calling arms from an imported library core or for calling arms from a stdlib core repeatedly.
134+
135+##### Syntax
136+
137+Regular: *2-fixed*.
138+
139+##### Examples
140+
141+With an imported core:
142+
143+```
144+> (sum -7 --7)
145+-find.sum
146+[crash message]
147+
148+> (sum:si -7 --7)
149+--0
150+
151+> =, si (sum -7 --7)
152+--0
153+```
154+
155+With a dojo-defined face:
156+
157+```
158+> =/ fan [bab=2 baz=[3 qux=4]]
159+ =, fan
160+ [bab qux.baz]
161+[2 4]
162+```
163+
164+;=
165+ ;h3
166+ ;div(id "tisdot"): =. "tisdot"
167+ ==
168+==
169+
170+`[%tsdt p=wing q=hoon r=hoon]`: change one leg in the subject.
171+
172+##### Expands to
173+
174+```
175+=>(%_(. p q) r)
176+```
177+
178+##### Syntax
179+
180+Regular: *3-fixed*.
181+
182+##### Discussion
183+
184+Technically the `=.` rune doesn't change the subject. It creates
185+a new subject just like the old one except for a changed value at `p`. Note that the mutation uses [`%_` ("cencab")](docs/reference/hoon-expressions/rune/cen#cencab), so the type at `p` doesn't change. Trying to change the value type results in a `nest-fail`.
186+
187+##### Examples
188+
189+```
190+> =+ a=[b=1 c=2]
191+ =. b.a 3
192+ a
193+[b=3 c=2]
194+
195+> =+ a=[b=1 c=2]
196+ =.(b.a 3 a)
197+[b=3 c=2]
198+
199+> =+ a=[b=1 c=2]
200+ =.(b.a "hello" a)
201+nest-fail
202+```
203+
204+;=
205+ ;h3
206+ ;div(id "tishep"): =- "tishep"
207+ ==
208+==
209+
210+`[%tshp p=hoon q=hoon]`: combine a new noun with the subject, inverted.
211+
212+##### Expands to
213+
214+```
215+=>([q .] p)
216+```
217+
218+##### Syntax
219+
220+Regular: *2-fixed*.
221+
222+##### Discussion
223+
224+`=-` is just like `=+` but its subexpressions are reversed. `=-` looks better than `=+` when the expression you're pinning to the subject is much smaller than the expression that uses it.
225+
226+##### Examples
227+
228+```
229+~zod:dojo> =foo |= a=@
230+ =+ b=1
231+ =- (add a b c)
232+ c=2
233+~zod:dojo> (foo 5)
234+8
235+```
236+
237+;=
238+ ;h3
239+ ;div(id "tisket"): =^ "tisket"
240+ ==
241+==
242+
243+`[%tskt p=skin q=wing r=hoon s=hoon]`: pin the head of a pair; change
244+a leg with the tail.
245+
246+##### Expands to
247+
248+```
249+=/(p -.r =.(q +.r s))
250+```
251+
252+##### Syntax
253+
254+Regular: *4-fixed*.
255+
256+##### Discussion
257+
258+`p` is a new name (possibly with type annotation, e.g., `a=@`) of a value to be pinned to the subject. The value of `p` is the head of the product of `r`. `q` is given the value of the tail of `r`'s product. Then `s` is evaluated against this new subject.
259+
260+We generally use `=^` when we have a state machine with a function, `r`, that
261+produces a cell, whose head is a result and whose tail is a new
262+state. The head value is given a new name `p`, and the
263+tail is stuffed back into wherever we stored the old state, `q`.
264+
265+This may also remind you of Haskell's State monad.
266+
267+##### Examples
268+
269+The `og` core is a stateful pseudo-random number generator.
270+We have to change the core state every time we generate a
271+random number, so we use `=^`:
272+
273+```
274+~zod:dojo> =+ rng=~(. og 420)
275+ =^ r1 rng (rads:rng 100)
276+ =^ r2 rng (rads:rng 100)
277+ [r1 r2]
278+[99 46]
279+```
280+
281+;=
282+ ;h3
283+ ;div(id "tisled"): =< "tisled"
284+ ==
285+==
286+
287+`[%tsgl p=hoon q=hoon]`: compose two expressions, inverted.
288+
289+##### Expands to
290+
291+```
292+=>(q p)
293+```
294+
295+##### Syntax
296+
297+Regular: *2-fixed*.
298+
299+Irregular: `foo:baz` is `=<(foo baz)`.
300+
301+##### Discussion
302+
303+`=<` is just `=>` backwards.
304+
305+##### Examples
306+
307+```
308+~zod:dojo> =<(b [a=1 b=2 c=3])
309+2
310+
311+~zod:dojo> =< b
312+ [a=1 b=2 c=3]
313+2
314+
315+~zod:dojo> b:[a=1 b=2 c=3]
316+2
317+
318+~zod:dojo> [. .]:(add 2 4)
319+[6 6]
320+```
321+
322+;=
323+ ;h3
324+ ;div(id "tislut"): =+ "tislus"
325+ ==
326+==
327+
328+
329+`[%tsls p=hoon q=hoon]`: combine a new noun with the subject.
330+
331+##### Expands to
332+
333+```
334+=>([p .] q)
335+```
336+
337+##### Syntax
338+
339+Regular: *2-fixed*.
340+
341+##### Discussion
342+
343+The subject of the `=+` expression, call it `a`, becomes the cell `[p a]` for the evaluation of `q`. That is, `=+` 'pins a value', `p`, to the head of the subject.
344+
345+Loosely speaking, `=+` is the simplest way of "declaring a variable."
346+
347+##### Examples
348+
349+;=
350+ ;h3
351+ ;div(id "tismic"): =; "tismic"
352+ ==
353+==
354+
355+`[%tssm p=skin q=hoon r=hoon]`: combine a named noun with the subject, possibly with type annotation; inverted order.
356+
357+##### Expands to
358+
359+```
360+=/(p r q)
361+```
362+
363+##### Syntax
364+
365+Regular: *3-fixed*.
366+
367+##### Discussion
368+
369+`=;` is exactly like `=/` except that the order of its last two subexpressions is reversed.
370+
371+##### Examples
372+
373+```
374+~zod:dojo> =foo |= a=@
375+ =/ b 1
376+ =; c=@ :(add a b c)
377+ 2
378+~zod:dojo> (foo 5)
379+8
380+```
381+
382+;=
383+ ;h3
384+ ;div(id "tisnet"): =/ "tisnet"
385+ ==
386+==
387+
388+`[%tsfs p=skin q=hoon r=hoon]`: combine a named noun with the subject, possibly with type annotation.
389+
390+##### Expands to
391+
392+*if `p` is a name*, (e.g. `a`):
393+
394+```
395+=+(^=(p q) r)
396+```
397+
398+*if `p` is a name with a type* (e.g., `a=@`):
399+
400+```
401+=+(^-(p q) r)
402+```
403+
404+### Compiler macro
405+
406+```
407+?@ p
408+ =+ p=q
409+ r
410+=+ ^-($=(p.p q.p) q)
411+r
412+```
413+
414+##### Syntax
415+
416+Regular: *3-fixed*.
417+
418+##### Discussion
419+
420+`p` can be either a name or a name=type. If it's just a name,
421+`=/` ("tisnet") "declares a type-inferred variable." If it has a type, `=/`
422+"declares a type-checked variable."
423+
424+##### Examples
425+
426+```
427+~zod:dojo> =foo |= a=@
428+ =/ b 1
429+ =/ c=@ 2
430+ :(add a b c)
431+~zod:dojo> (foo 5)
432+8
433+```
434+
435+;=
436+ ;h3
437+ ;div(id "tissig"): =~ "tissig"
438+ ==
439+==
440+
441+
442+`[%tssg p=(list hoon)]`: compose many expressions.
443+
444+##### Produces
445+
446+The product of the chain composition.
447+
448+##### Syntax
449+
450+Regular: *running*.
451+
452+##### Examples
453+
454+```
455+~zod:dojo> =~ [sub (mul 3 20) (add 10 20)]
456+ (sub +)
457+ +(.)
458+ ==
459+31
460+
461+~zod:dojo> =foo =| n=@
462+ =< =~ increment
463+ increment
464+ increment
465+ n
466+ ==
467+ |%
468+ ++ increment
469+ ..increment(n +(n))
470+ --
471+~zod:dojo> foo
472+3
473+```
474+
475+;=
476+ ;h3
477+ ;div(id "tistar"): =* "tistar"
478+ ==
479+==
480+
481+`[%tstr p=term q=hoon r=hoon]`: define an alias.
482+
483+##### Produces
484+
485+`r`, compiled with a subject in which `p` is aliased to `q`.
486+
487+##### Syntax
488+
489+Regular: *3-fixed*.
490+
491+##### Discussion
492+
493+The difference between aliasing and pinning is that pinning changes the subject, but for aliasing the subject noun stays the same. The aliased expression, `q`, is recorded in the type information of `p`. `q` is calculated every time you use the `p` alias.
494+
495+##### Examples
496+
497+```
498+~zod:dojo>
499+ =+ a=1
500+ =* b a
501+ [a b]
502+[1 1]
503+
504+~zod:dojo>
505+ =+ a=1
506+ =* b a
507+ =. a 2
508+ [a b]
509+[2 2]
510+```
511+
512+;=
513+ ;h3
514+ ;div(id "tiswut"): =? "tiswut"
515+ ==
516+==
517+
518+`[$tswt p=wing q=hoon r=hoon s=hoon]`: conditionally change one leg in the subject.
519+
520+##### Expands to
521+
522+```
523+=. p ?:(q r p)
524+s
525+```
526+
527+##### Syntax
528+
529+Regular: *4-fixed*.
530+
531+##### Discussion
532+
533+Use `=?` to replace the value of leg `p` with `r` on condition `q`. As
534+usual, we are not actually mutating the subject, just creating
535+a new subject with a changed value. The change in value includes a
536+type check against the old subject; the type of `r` must nest under
537+the type of `p`.
538+
539+##### Examples
540+
541+```
542+> =a 12
543+
544+> =?(a =(1 1) 22 a)
545+22
546+
547+> =?(a =(1 2) 22 a)
548+12
549+```
reference/hoon-expressions/rune/tis/ban.udondeleted−28
@@ -1,28 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'1'
4− title/'=> "tisban"'
5− ==
6−;>
7−
8−# `=> "tisban"`
9−
10−`[%tsgr p=hoon q=hoon]`: compose two expressions.
11−
12−## Produces
13−
14−the product of `q`, with the product of `p` taken as the subject.
15−
16−## Syntax
17−
18−Regular: *2-fixed*.
19−
20−## Examples
21−
22−```
23−> =>([a=1 b=2 c=3] b)
24−2
25−
26−> =>((add 2 4) [. .])
27−[6 6]
28−```
reference/hoon-expressions/rune/tis/bar.udondeleted−37
@@ -1,37 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'12'
4− title/'=| "tisbar"'
5− ==
6−;>
7−
8−# `=| "tisbar"`
9−
10−`[%tsbr p=spec q=hoon]`: combine a default type value with the subject.
11−
12−## Expands to
13−
14−```
15−=+(*p q)
16−```
17−
18−## Syntax
19−
20−Regular: *2-fixed*.
21−
22−## Discussion
23−
24−The default (or 'bunt') value of `p` is pinned to the head of the subject. Usually `p` includes a name for ease of reference.
25−
26−Speaking more loosely, `=|` usually "declares a variable" which is "uninitialized," presumably because you'll set it in a loop or similar.
27−
28−## Examples
29−
30−```
31−~zod:dojo> =foo |= a=@
32− =| b=@
33− =- :(add a b c)
34− c=2
35−~zod:dojo> (foo 5)
36−7
37−```
reference/hoon-expressions/rune/tis/col.udondeleted−35
@@ -1,35 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'3'
4− title/'=: "tiscol"'
5− ==
6−;>
7−
8−# `=: "tiscol"`
9−
10−`[%tscl p=(list (pair wing hoon)) q=hoon]`: change multiple legs in the subject.
11−
12−## Expands to
13−
14−```
15−=>(%_(. p) q)
16−```
17−
18−## Syntax
19−
20−Regular: *jogging*, then *1-fixed*.
21−
22−## Discussion
23−
24−This rune is like `=.`, but for modifying the values of multiple legs of the subject.
25−
26−## Examples
27−
28−```
29−~zod:dojo> =+ a=[b=1 c=2]
30− =: c.a 4
31− b.a 3
32− ==
33− a
34−[b=3 c=4]
35−```
reference/hoon-expressions/rune/tis/com.udondeleted−41
@@ -1,41 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'5'
4− title/'=, "tiscom"'
5− ==
6−;>
7−
8−# `=, "tiscom"`
9−
10−`[%tscm p=hoon q=hoon]`: expose namespace
11−
12−`p` evaluates to a noun with some namespace. From within `q` you may access `p`'s names without a wing path (i.e., you can use face `b` rather than `b.p`). This is especially useful for calling arms from an imported library core or for calling arms from a stdlib core repeatedly.
13−
14−## Syntax
15−
16−Regular: *2-fixed*.
17−
18−## Examples
19−
20−With an imported core:
21−
22−```
23−> (sum -7 --7)
24−-find.sum
25−[crash message]
26−
27−> (sum:si -7 --7)
28−--0
29−
30−> =, si (sum -7 --7)
31−--0
32−```
33−
34−With a dojo-defined face:
35−
36−```
37−> =/ fan [bab=2 baz=[3 qux=4]]
38− =, fan
39− [bab qux.baz]
40−[2 4]
41−```
reference/hoon-expressions/rune/tis/dot.udondeleted−42
@@ -1,42 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'2'
4− title/'=. "tisdot"'
5− ==
6−;>
7−
8−# `=. "tisdot"`
9−
10−`[%tsdt p=wing q=hoon r=hoon]`: change one leg in the subject.
11−
12−## Expands to
13−
14−```
15−=>(%_(. p q) r)
16−```
17−
18−## Syntax
19−
20−Regular: *3-fixed*.
21−
22−## Discussion
23−
24−Technically the `=.` rune doesn't change the subject. It creates
25−a new subject just like the old one except for a changed value at `p`. Note that the mutation uses [`%_` ("cencab")](../../cen/cab/), so the type at `p` doesn't change. Trying to change the value type results in a `nest-fail`.
26−
27−## Examples
28−
29−```
30−> =+ a=[b=1 c=2]
31− =. b.a 3
32− a
33−[b=3 c=2]
34−
35−> =+ a=[b=1 c=2]
36− =.(b.a 3 a)
37−[b=3 c=2]
38−
39−> =+ a=[b=1 c=2]
40− =.(b.a "hello" a)
41−nest-fail
42−```
reference/hoon-expressions/rune/tis/hep.udondeleted−35
@@ -1,35 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'9'
4− title/'=- "tishep"'
5− ==
6−;>
7−
8−# `=- "tishep"`
9−
10−`[%tshp p=hoon q=hoon]`: combine a new noun with the subject, inverted.
11−
12−## Expands to
13−
14−```
15−=>([q .] p)
16−```
17−
18−## Syntax
19−
20−Regular: *2-fixed*.
21−
22−## Discussion
23−
24−`=-` is just like `=+` but its subexpressions are reversed. `=-` looks better than `=+` when the expression you're pinning to the subject is much smaller than the expression that uses it.
25−
26−## Examples
27−
28−```
29−~zod:dojo> =foo |= a=@
30− =+ b=1
31− =- (add a b c)
32− c=2
33−~zod:dojo> (foo 5)
34−8
35−```
reference/hoon-expressions/rune/tis/ket.udondeleted−46
@@ -1,46 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'4'
4− title/'=^ "tisket"'
5− ==
6−;>
7−
8−# `=^ "tisket"`
9−
10−`[%tskt p=skin q=wing r=hoon s=hoon]`: pin the head of a pair; change
11−a leg with the tail.
12−
13−## Expands to
14−
15−```
16−=/(p -.r =.(q +.r s))
17−```
18−
19−## Syntax
20−
21−Regular: *4-fixed*.
22−
23−## Discussion
24−
25−`p` is a new name (possibly with type annotation, e.g., `a=@`) of a value to be pinned to the subject. The value of `p` is the head of the product of `r`. `q` is given the value of the tail of `r`'s product. Then `s` is evaluated against this new subject.
26−
27−We generally use `=^` when we have a state machine with a function, `r`, that
28−produces a cell, whose head is a result and whose tail is a new
29−state. The head value is given a new name `p`, and the
30−tail is stuffed back into wherever we stored the old state, `q`.
31−
32−This may also remind you of Haskell's State monad.
33−
34−## Examples
35−
36−The `og` core is a stateful pseudo-random number generator.
37−We have to change the core state every time we generate a
38−random number, so we use `=^`:
39−
40−```
41−~zod:dojo> =+ rng=~(. og 420)
42− =^ r1 rng (rads:rng 100)
43− =^ r2 rng (rads:rng 100)
44− [r1 r2]
45−[99 46]
46−```
reference/hoon-expressions/rune/tis/led.udondeleted−43
@@ -1,43 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'6'
4− title/'=< "tisled"'
5− ==
6−;>
7−
8−# `=< "tisled"`
9−
10−`[%tsgl p=hoon q=hoon]`: compose two expressions, inverted.
11−
12−## Expands to
13−
14−```
15−=>(q p)
16−```
17−
18−## Syntax
19−
20−Regular: *2-fixed*.
21−
22−Irregular: `foo:baz` is `=<(foo baz)`.
23−
24−## Discussion
25−
26−`=<` is just `=>` backwards.
27−
28−## Examples
29−
30−```
31−~zod:dojo> =<(b [a=1 b=2 c=3])
32−2
33−
34−~zod:dojo> =< b
35− [a=1 b=2 c=3]
36−2
37−
38−~zod:dojo> b:[a=1 b=2 c=3]
39−2
40−
41−~zod:dojo> [. .]:(add 2 4)
42−[6 6]
43−```
reference/hoon-expressions/rune/tis/lus.udondeleted−37
@@ -1,37 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'8'
4− title/'=+ "tislus"'
5− ==
6−;>
7−
8−# `=+ "tislus"`
9−
10−`[%tsls p=hoon q=hoon]`: combine a new noun with the subject.
11−
12−## Expands to
13−
14−```
15−=>([p .] q)
16−```
17−
18−## Syntax
19−
20−Regular: *2-fixed*.
21−
22−## Discussion
23−
24−The subject of the `=+` expression, call it `a`, becomes the cell `[p a]` for the evaluation of `q`. That is, `=+` 'pins a value', `p`, to the head of the subject.
25−
26−Loosely speaking, `=+` is the simplest way of "declaring a variable."
27−
28−## Examples
29−
30−```
31−~zod:dojo> =foo |= a=@
32− =+ b=1
33− =+ c=2
34− :(add a b c)
35−~zod:dojo> (foo 5)
36−8
37−```
reference/hoon-expressions/rune/tis/mic.udondeleted−35
@@ -1,35 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'11'
4− title/'=; "tismic"'
5− ==
6−;>
7−
8−# `=; "tismic"`
9−
10−`[%tssm p=skin q=hoon r=hoon]`: combine a named noun with the subject, possibly with type annotation; inverted order.
11−
12−## Expands to
13−
14−```
15−=/(p r q)
16−```
17−
18−## Syntax
19−
20−Regular: *3-fixed*.
21−
22−## Discussion
23−
24−`=;` is exactly like `=/` except that the order of its last two subexpressions is reversed.
25−
26−## Examples
27−
28−```
29−~zod:dojo> =foo |= a=@
30− =/ b 1
31− =; c=@ :(add a b c)
32− 2
33−~zod:dojo> (foo 5)
34−8
35−```
reference/hoon-expressions/rune/tis/net.udondeleted−55
@@ -1,55 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'10'
4− title/'=/ "tisnet"'
5− ==
6−;>
7−
8−# `=/ "tisnet"`
9−
10−`[%tsfs p=skin q=hoon r=hoon]`: combine a named noun with the subject, possibly with type annotation.
11−
12−## Expands to
13−
14−*if `p` is a name*, (e.g. `a`):
15−
16−```
17−=+(^=(p q) r)
18−```
19−
20−*if `p` is a name with a type* (e.g., `a=@`):
21−
22−```
23−=+(^-(p q) r)
24−```
25−
26−### Compiler macro
27−
28−```
29−?@ p
30− =+ p=q
31− r
32−=+ ^-($=(p.p q.p) q)
33−r
34−```
35−
36−## Syntax
37−
38−Regular: *3-fixed*.
39−
40−## Discussion
41−
42−`p` can be either a name or a name=type. If it's just a name,
43−`=/` ("tisnet") "declares a type-inferred variable." If it has a type, `=/`
44−"declares a type-checked variable."
45−
46−## Examples
47−
48−```
49−~zod:dojo> =foo |= a=@
50− =/ b 1
51− =/ c=@ 2
52− :(add a b c)
53−~zod:dojo> (foo 5)
54−8
55−```
reference/hoon-expressions/rune/tis/sig.udondeleted−41
@@ -1,41 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'7'
4− title/'=~ "tissig"'
5− ==
6−;>
7−
8−# `=~ "tissig"`
9−
10−`[%tssg p=(list hoon)]`: compose many expressions.
11−
12−## Produces
13−
14−The product of the chain composition.
15−
16−## Syntax
17−
18−Regular: *running*.
19−
20−## Examples
21−
22−```
23−~zod:dojo> =~ [sub (mul 3 20) (add 10 20)]
24− (sub +)
25− +(.)
26− ==
27−31
28−
29−~zod:dojo> =foo =| n=@
30− =< =~ increment
31− increment
32− increment
33− n
34− ==
35− |%
36− ++ increment
37− ..increment(n +(n))
38− --
39−~zod:dojo> foo
40−3
41−```
reference/hoon-expressions/rune/tis/tar.udondeleted−39
@@ -1,39 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'13'
4− title/'=* "tistar"'
5− ==
6−;>
7−
8−# `=* "tistar"`
9−
10−`[%tstr p=term q=hoon r=hoon]`: define an alias.
11−
12−## Produces
13−
14−`r`, compiled with a subject in which `p` is aliased to `q`.
15−
16−## Syntax
17−
18−Regular: *3-fixed*.
19−
20−## Discussion
21−
22−The difference between aliasing and pinning is that pinning changes the subject, but for aliasing the subject noun stays the same. The aliased expression, `q`, is recorded in the type information of `p`. `q` is calculated every time you use the `p` alias.
23−
24−## Examples
25−
26−```
27−~zod:dojo>
28− =+ a=1
29− =* b a
30− [a b]
31−[1 1]
32−
33−~zod:dojo>
34− =+ a=1
35− =* b a
36− =. a 2
37− [a b]
38−[2 2]
39−```
reference/hoon-expressions/rune/tis/wut.udondeleted−41
@@ -1,41 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'14'
4− title/'=? "tiswut"'
5− ==
6−;>
7−
8−# `=? "tiswut"`
9−
10−`[$tswt p=wing q=hoon r=hoon s=hoon]`: conditionally change one leg in the subject.
11−
12−## Expands to
13−
14−```
15−=. p ?:(q r p)
16−s
17−```
18−
19−## Syntax
20−
21−Regular: *4-fixed*.
22−
23−## Discussion
24−
25−Use `=?` to replace the value of leg `p` with `r` on condition `q`. As
26−usual, we are not actually mutating the subject, just creating
27−a new subject with a changed value. The change in value includes a
28−type check against the old subject; the type of `r` must nest under
29−the type of `p`.
30−
31−## Examples
32−
33−```
34−> =a 12
35−
36−> =?(a =(1 1) 22 a)
37−22
38−
39−> =?(a =(1 2) 22 a)
40−12
41−```
reference/hoon-expressions/rune/wut.udon+578−5
@@ -10,7 +10,7 @@
10Hoon has the usual program control branches. It also has the usual logical
10Hoon has the usual program control branches. It also has the usual logical
11operators: AND `?&`, OR `?|`, and NOT `?!`. It also has a `?=` rune that tests
11operators: AND `?&`, OR `?|`, and NOT `?!`. It also has a `?=` rune that tests
12whether a value matches a given type. In the course of type inference, Hoon
12whether a value matches a given type. In the course of type inference, Hoon
13−learns from `?=` tests in the test condition of [`?:` ("wutcol")](./col/)
13+learns from `?=` tests in the test condition of [`?:` ("wutcol")](#wutcol)
14expressions.
14expressions.
15
15
16## Overview
16## Overview
@@ -23,9 +23,9 @@ type for the branches of the `?:`. Branch inference also works
23for expressions which expand to `?:`.
23for expressions which expand to `?:`.
24
24
25The test does not have to be a single `?=`; the compiler can
25The test does not have to be a single `?=`; the compiler can
26−analyze arbitrary boolean logic ([`?&` ("wutpam")](./pam/),
26+analyze arbitrary boolean logic ([`?&` ("wutpam")](#wutpam),
27−[`?|` ("wutbar")](./bar/), [`?!` ("wutzap")](./zap/)) with full
27+[`?|` ("wutbar")](#wutbar), [`?!` ("wutzap")](#wutzap)) with full
28−short-circuiting. Equality tests ([`.=` ("dottis")](../dot/tis/)) are *not*
28+short-circuiting. Equality tests ([`.=` ("dottis")](docs/reference/hoon-expressions/rune/dot#tis/)) are *not*
29analyzed.
29analyzed.
30
30
31If the compiler detects that the branch is degenerate (only one
31If the compiler detects that the branch is degenerate (only one
@@ -33,4 +33,577 @@ side is taken), it fails with an error.
33
33
34## Runes
34## Runes
35
35
36−;list(datapreview "true", classname "runes");
36+;=
37+ ;h3
38+ ;div(id "wutban"): ?> "wutban"
39+ ==
40+==
41+
42+`[%wtbn p=hoon q=hoon]`: positive assertion.
43+
44+##### Expands to
45+
46+```
47+?.(p !! q)
48+```
49+
50+##### Syntax
51+
52+Regular: *2-fixed*.
53+
54+##### Discussion
55+
56+`?>` is used to force a crash when some condition `p` doesn't yield 'yes', `%.y`.
57+
58+It can be used for type inference, with the `?=` rune, to specify the type of a value.
59+
60+##### Examples
61+
62+```
63+> ?>(=(3 3) %foo)
64+%foo
65+
66+> ?>(=(3 4) %foo)
67+ford: build failed
68+
69+> =a `*`123
70+
71+> `@`a
72+nest-fail
73+
74+> ?>(?=(@ a) `@`a)
75+123
76+```
77+
78+;=
79+ ;h3
80+ ;div(id "wutbar"): ?> "wutbar"
81+ ==
82+==
83+
84+`[%wtbr p=(list hoon)]`: logical OR.
85+
86+##### Expands to
87+
88+*Pseudocode*: `a`, `b`, `c`, ... as elements of `p`:
89+
90+```
91+?:(a & ?:(b & ?:(c & ?:(... ?:(z & |)))))
92+```
93+
94+##### Compiler macro
95+
96+```
97+|-
98+?~ p
99+ |
100+?: i.p
101+ &
102+$(p t.p)
103+```
104+
105+##### Syntax
106+
107+Regular: *running*.
108+
109+Irregular: `|(foo bar baz)` is `?|(foo bar baz)`.
110+
111+##### Examples
112+
113+```
114+~zod:dojo> |(=(6 42) =(42 42))
115+%.y
116+
117+~zod:dojo> |(=(6 42) =(42 43))
118+%.n
119+```
120+
121+;=
122+ ;h3
123+ ;div(id "wutcol"): ?: "wutcol"
124+ ==
125+==
126+
127+`[%wtcl p=hoon q=hoon r=hoon]`: branch on a boolean test.
128+
129+##### Produces
130+
131+If `p` produces yes, `%.y`, then `q`. If `p` produces no, `%.n`, then `r`.
132+If `p` is not a boolean, compiler yells at you.
133+
134+##### Type inference
135+
136+The subject types of `q` and `r` are constrained to match any pattern-matching algebra in `p`. The analysis, which is conservative, understands any combination of [`?=`](#wuttis), [`?&`](#wutpad), [`?|`](#wutbar), and [`?!`](#wutzap), and infers the type of the subject appropriately when compiling.
137+
138+If test analysis reveals that either branch is never taken, or if `p` is not a boolean, compilation fails. An untaken branch is indicated with `mint-lost`.
139+
140+##### Syntax
141+
142+Regular: *3-fixed*.
143+
144+##### Discussion
145+
146+Short-circuiting in boolean tests works as you'd expect
147+and includes the expected inference. For instance,
148+if you write `?&(a b)`, `b` is only executed if `a` is
149+positive, and compiled with that assumption.
150+
151+Note also that all other branching expressions reduce to `?:`.
152+
153+##### Examples
154+
155+```
156+~zod:dojo> ?:((gth 1 0) 3 4)
157+3
158+
159+~zod:dojo> ?: (gth 1 0)
160+ 3
161+ 4
162+3
163+
164+~zod:dojo> ?:((gth 1 2) 3 4)
165+4
166+
167+~zod:dojo> ?: (gth 1 2)
168+ 3
169+ 4
170+4
171+```
172+
173+;=
174+ ;h3
175+ ;div(id "wutdot"): ?. "wutdot"
176+ ==
177+==
178+
179+`[%wtdt p=hoon q=hoon r=hoon]`: branch on a boolean test, inverted.
180+
181+##### Expands to
182+
183+```
184+?:(p r q)
185+```
186+
187+##### Syntax
188+
189+Regular: *3-fixed*.
190+
191+##### Discussion
192+
193+`?.` is just like `?:`, but with its last two subexpressions reversed.
194+
195+As is usual with inverted forms, use `?.` when the yes-case expression is much taller and/or wider than the no-case expression.
196+
197+##### Examples
198+
199+```
200+~zod:dojo> ?.((gth 1 2) 3 4)
201+3
202+
203+~zod:dojo> ?.(?=(%a 'a') %not-a %yup)
204+%yup
205+
206+~zod:dojo> ?. %.y
207+ 'this false case is less heavy than the true case'
208+ ?: =(2 3)
209+ 'two not equal to 3'
210+ 'but see how \'r is much heavier than \'q?'
211+'but see how \'r is much heavier than \'q?'
212+```
213+
214+;=
215+ ;h3
216+ ;div(id "wuthep"): ?- "wuthep"
217+ ==
218+==
219+
220+`[%wthp p=wing q=(list (pair spec value))]`: switch against a union, with no default.
221+
222+##### Expands to
223+
224+*Pseudocode*: `a`, `b`, `c`, ... as elements of `q`:
225+
226+```
227+?: ?=(p.a) q.a
228+?: ?=(p.b) q.b
229+?: ?=(p.c) q.c
230+...
231+~|(%mint-lost !!)
232+```
233+
234+##### Compiler macro
235+
236+```
237+|-
238+?. q
239+ ~|(%mint-lost !!)
240+?: ?=(p.i.q p)
241+ q.i.q
242+$(q t.q)
243+```
244+
245+##### Syntax
246+
247+Regular: *1-fixed*, then *jogging*.
248+
249+##### Discussion
250+
251+The `?-` rune is for a conditional expression in which the type of `p` determines which branch is taken. Usually the type of `p` is a union of other types. There is no default branch.
252+
253+The compiler makes sure that your code neither misses a case of
254+the union, nor includes a double case that isn't there. This is
255+not special handling for `?-`, just a consequence of the
256+semantics of `?:`, which `?-` reduces to.
257+
258+A missing case will throw the `mint-lost` error. An extra case
259+will throw `mint-vain`.
260+
261+##### Examples
262+
263+```
264+~zod:dojo> =cor |= vat=?(%a %b)
265+ ?- vat
266+ %a 20
267+ %b 42
268+ ==
269+
270+~zod:dojo> (cor %a)
271+20
272+
273+~zod:dojo> (cor %b)
274+42
275+
276+~zod:dojo> (cor %c)
277+! nest-fail
278+```
279+
280+;=
281+ ;h3
282+ ;div(id "wutket"): ?^ "wutket"
283+ ==
284+==
285+
286+`[%wtkt p=wing q=hoon r=hoon]`: branch on whether a wing
287+of the subject is a cell.
288+
289+##### Expands to
290+
291+```
292+?:(?=(^ p) q r)
293+```
294+
295+##### Syntax
296+
297+Regular: *3-fixed*.
298+
299+##### Discussion
300+
301+The type of the wing, `p`, must not be known to be either an atom or a cell, or else you'll get a `mint-vain` error at compile time. `mint-vain` means that one of the `?^` branches, `q` or `r`, is never taken.
302+
303+##### Examples
304+
305+```
306+~zod:dojo> ?^(0 1 2)
307+! mint-vain
308+! exit
309+
310+~zod:dojo> ?^(`*`0 1 2)
311+2
312+
313+~zod:dojo> ?^(`*`[1 2] 3 4)
314+3
315+```
316+
317+;=
318+ ;h3
319+ ;div(id "wutled"): ?< "wutled"
320+ ==
321+==
322+
323+
324+# `?< "wutled"`
325+
326+`[%wtgl p=hoon q=hoon]`: negative assertion.
327+
328+##### Expands to
329+
330+```
331+?:(p !! q)
332+```
333+
334+##### Syntax
335+
336+Regular: *2-fixed*.
337+
338+##### Discussion
339+
340+`?<` is used to force a crash when some condition `p` doesn't yield 'no', `%.n`.
341+
342+It can be used for type inference with the `?=` rune, much like the `?>` rune.
343+
344+##### Examples
345+
346+```
347+> ?<(=(3 4) %foo)
348+%foo
349+
350+> ?<(=(3 3) %foo)
351+ford: build failed
352+
353+> =a `*`[12 14]
354+
355+> `^`a
356+nest-fail
357+
358+> ?<(?=(@ a) `^`a)
359+[12 14]
360+```
361+
362+;=
363+ ;h3
364+ ;div(id "wutlus"): ?+ "wutlus"
365+ ==
366+==
367+
368+`[%wtls p=wing q=hoon r=(list (pair spec hoon))]`: switch against
369+a union, with a default.
370+
371+##### Expands to
372+
373+*Pseudocode*: `a`, `b`, `c`, ... as elements of `r`:
374+
375+```
376+?: ?=(p.a) q.a
377+?: ?=(p.b) q.b
378+?: ?=(p.c) q.c
379+...
380+q
381+```
382+
383+##### Compiler macro
384+
385+```
386+|-
387+?. r
388+ q
389+?: ?=(p.i.r p)
390+ q.i.r
391+$(r t.r)
392+```
393+
394+##### Syntax
395+
396+Regular: *2-fixed*, then *jogging*.
397+
398+##### Discussion
399+
400+The `?+` rune is for a conditional expression in which the type of `p` determines which branch is taken. Usually the type of `p` is a union of other types. If `p`'s type doesn't match the case for any given branch, the default expression, `q`, is evaluated.
401+
402+If there is a case that is never taken you'll get a `mint-vain` error.
403+
404+##### Examples
405+
406+```
407+~zod:dojo> =cor |= vat=?(%a %b)
408+ ?+ vat 240
409+ %a 20
410+ %b 42
411+ ==
412+
413+~zod:dojo> (cor %a)
414+20
415+
416+~zod:dojo> (cor %b)
417+42
418+
419+~zod:dojo> (cor %c)
420+240
421+```
422+
423+;=
424+ ;h3
425+ ;div(id "wutpad"): ?& "wutpad"
426+ ==
427+==
428+
429+`[%wtpd p=(list hoon)]`: logical AND.
430+
431+##### Expands to
432+
433+*Pseudocode*: `a`, `b`, `c`, ... as elements of `p`:
434+
435+```
436+?.(a | ?.(b | ?.(c | ?.(... ?.(z | &)))))
437+```
438+
439+##### Compiler macro
440+
441+```
442+|-
443+?~ p
444+ &
445+?. i.p
446+ |
447+$(p t.p)
448+```
449+
450+##### Syntax
451+
452+Regular: *running*.
453+
454+Irregular: `&(foo bar baz)` is `?&(foo bar baz)`.
455+
456+##### Examples
457+
458+```
459+~zod:dojo> &(=(6 6) =(42 42))
460+%.y
461+
462+~zod:dojo> &(=(6 7) =(42 43))
463+%.n
464+```
465+
466+;=
467+ ;h3
468+ ;div(id "wutsig"): ?~ "wutsig"
469+ ==
470+==
471+
472+`[%wtsg p=wing q=hoon r=hoon]`: branch on whether a wing of the subject is null.
473+
474+##### Expands to
475+
476+```
477+?:(?=($~ p) q r)
478+```
479+
480+##### Syntax
481+
482+Regular: *3-fixed*.
483+
484+##### Discussion
485+
486+It's bad style to use `?~` to test for any zero atom. Use it only for a true null, `~`.
487+
488+##### Examples
489+
490+```
491+~zod:dojo> =foo ""
492+
493+~zod:dojo> ?~(foo 1 2)
494+1
495+```
496+
497+;=
498+ ;h3
499+ ;div(id "wuttis"): ?= "wuttis"
500+ ==
501+==
502+
503+`[%wtts p=spec q=wing]`: test pattern match.
504+
505+##### Produces
506+
507+`%.y` (yes) if the noun at `q` is in the type of `p`; `%.n` (no) otherwise.
508+
509+##### Syntax
510+
511+Regular: *2-fixed*.
512+
513+##### Discussion
514+
515+`?=` is not as powerful as it might seem. For instance, it
516+can't generate a loop -- you cannot (and should not) use it to
517+test whether a `*` is a `(list @)`. Nor can it validate atomic
518+auras.
519+
520+Patterns should be as weak as possible. Unpack one layer of
521+union at a time. Don't confirm things the type system knows.
522+
523+For example, when matching from a tagged union for the type `[%foo p=@
524+q=[@ @]]`, the appropriate pattern is `[%foo *]`. You have one
525+question, which is whether the head of the noun is `%foo`.
526+
527+A common error is `find.$`, meaning `p` is not a type.
528+
529+##### Examples
530+
531+```
532+~zod:dojo> =bar [%foo %bar %baz]
533+~zod:dojo> ?=([%foo *] bar)
534+%.y
535+```
536+
537+;=
538+ ;h3
539+ ;div(id "wutvat"): ?@ "wutvat"
540+ ==
541+==
542+
543+`[%wtpt p=wing q=hoon r=hoon]`: branch on whether a wing of the subject is an atom.
544+
545+##### Expands to
546+
547+```
548+?:(?=(@ p) q r)
549+```
550+
551+##### Syntax
552+
553+Regular: *3-fixed*.
554+
555+##### Discussion
556+
557+The type of the wing, `p`, must not be known to be either an atom or a cell, or else you'll get a `mint-vain` error at compile time. `mint-vain` means that one of the `?@` branches, `q` or `r`, is never taken.
558+
559+##### Examples
560+
561+```
562+~zod:dojo> ?@(0 1 2)
563+! mint-vain
564+! exit
565+
566+~zod:dojo> ?@(`*`0 1 2)
567+1
568+
569+~zod:dojo> ?@(`*`[1 2] 3 4)
570+4
571+```
572+
573+;=
574+ ;h3
575+ ;div(id "wutzap"): ?! "wutzaps"
576+ ==
577+==
578+
579+`[%wtzp p=hoon]`: logical NOT.
580+
581+##### Expands to
582+
583+```
584+.=(| p)
585+```
586+
587+Produces the logical NOT of `p`.
588+
589+##### Syntax
590+
591+Regular: *1-fixed*.
592+
593+Irregular: `!foo` is `?!(foo)`.
594+
595+##### Examples
596+
597+```
598+~zod:dojo> ?!(.=(1 2))
599+%.y
600+
601+~zod:dojo> !&
602+%.n
603+
604+~zod:dojo> !|
605+%.y
606+
607+~zod:dojo> !(gth 5 6)
608+%.y
609+```
reference/hoon-expressions/rune/wut/ban.udondeleted−44
@@ -1,44 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'7'
4− title/'?> "wutban"'
5− ==
6−;>
7−
8−# `?> "wutban"`
9−
10−`[%wtbn p=hoon q=hoon]`: positive assertion.
11−
12−## Expands to
13−
14−```
15−?.(p !! q)
16−```
17−
18−## Syntax
19−
20−Regular: *2-fixed*.
21−
22−## Discussion
23−
24−`?>` is used to force a crash when some condition `p` doesn't yield 'yes', `%.y`.
25−
26−It can be used for type inference, with the `?=` rune, to specify the type of a value.
27−
28−## Examples
29−
30−```
31−> ?>(=(3 3) %foo)
32−%foo
33−
34−> ?>(=(3 4) %foo)
35−ford: build failed
36−
37−> =a `*`123
38−
39−> `@`a
40−nest-fail
41−
42−> ?>(?=(@ a) `@`a)
43−123
44−```
reference/hoon-expressions/rune/wut/bar.udondeleted−45
@@ -1,45 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'10'
4− title/'?| "wutbar"'
5− ==
6−;>
7−
8−# `?| "wutbar"`
9−
10−`[%wtbr p=(list hoon)]`: logical OR.
11−
12−## Expands to
13−
14−*Pseudocode*: `a`, `b`, `c`, ... as elements of `p`:
15−
16−```
17−?:(a & ?:(b & ?:(c & ?:(... ?:(z & |)))))
18−```
19−
20−### Compiler macro
21−
22−```
23−|-
24−?~ p
25− |
26−?: i.p
27− &
28−$(p t.p)
29−```
30−
31−## Syntax
32−
33−Regular: *running*.
34−
35−Irregular: `|(foo bar baz)` is `?|(foo bar baz)`.
36−
37−## Examples
38−
39−```
40−~zod:dojo> |(=(6 42) =(42 42))
41−%.y
42−
43−~zod:dojo> |(=(6 42) =(42 43))
44−%.n
45−```
reference/hoon-expressions/rune/wut/col.udondeleted−54
@@ -1,54 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'1'
4− title/'?: "wutcol"'
5− ==
6−;>
7−
8−# `?: "wutcol"`
9−
10−`[%wtcl p=hoon q=hoon r=hoon]`: branch on a boolean test.
11−
12−## Produces
13−
14−If `p` produces yes, `%.y`, then `q`. If `p` produces no, `%.n`, then `r`.
15−If `p` is not a boolean, compiler yells at you.
16−
17−### Type inference
18−
19−The subject types of `q` and `r` are constrained to match any pattern-matching algebra in `p`. The analysis, which is conservative, understands any combination of [`?=`](../tis/), [`?&`](../pad/), [`?|`](../bar/), and [`?!`](../zap/), and infers the type of the subject appropriately when compiling.
20−
21−If test analysis reveals that either branch is never taken, or if `p` is not a boolean, compilation fails. An untaken branch is indicated with `mint-lost`.
22−
23−## Syntax
24−
25−Regular: *3-fixed*.
26−
27−## Discussion
28−
29−Short-circuiting in boolean tests works as you'd expect
30−and includes the expected inference. For instance,
31−if you write `?&(a b)`, `b` is only executed if `a` is
32−positive, and compiled with that assumption.
33−
34−Note also that all other branching expressions reduce to `?:`.
35−
36−## Examples
37−
38−```
39−~zod:dojo> ?:((gth 1 0) 3 4)
40−3
41−
42−~zod:dojo> ?: (gth 1 0)
43− 3
44− 4
45−3
46−
47−~zod:dojo> ?:((gth 1 2) 3 4)
48−4
49−
50−~zod:dojo> ?: (gth 1 2)
51− 3
52− 4
53−4
54−```
reference/hoon-expressions/rune/wut/dot.udondeleted−43
@@ -1,43 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'6'
4− title/'?. "wutdot"'
5− ==
6−;>
7−
8−# `?. "wutdot"`
9−
10−`[%wtdt p=hoon q=hoon r=hoon]`: branch on a boolean test, inverted.
11−
12−## Expands to
13−
14−```
15−?:(p r q)
16−```
17−
18−## Syntax
19−
20−Regular: *3-fixed*.
21−
22−## Discussion
23−
24−`?.` is just like `?:`, but with its last two subexpressions reversed.
25−
26−As is usual with inverted forms, use `?.` when the yes-case expression is much taller and/or wider than the no-case expression.
27−
28−## Examples
29−
30−```
31−~zod:dojo> ?.((gth 1 2) 3 4)
32−3
33−
34−~zod:dojo> ?.(?=(%a 'a') %not-a %yup)
35−%yup
36−
37−~zod:dojo> ?. %.y
38− 'this false case is less heavy than the true case'
39− ?: =(2 3)
40− 'two not equal to 3'
41− 'but see how \'r is much heavier than \'q?'
42−'but see how \'r is much heavier than \'q?'
43−```
reference/hoon-expressions/rune/wut/hep.udondeleted−68
@@ -1,68 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'4'
4− title/'?- "wuthep"'
5− ==
6−;>
7−
8−# `?- "wuthep"`
9−
10−`[%wthp p=wing q=(list (pair spec value))]`: switch against a union, with no default.
11−
12−## Expands to
13−
14−*Pseudocode*: `a`, `b`, `c`, ... as elements of `q`:
15−
16−```
17−?: ?=(p.a) q.a
18−?: ?=(p.b) q.b
19−?: ?=(p.c) q.c
20−...
21−~|(%mint-lost !!)
22−```
23−
24−### Compiler macro
25−
26−```
27−|-
28−?. q
29− ~|(%mint-lost !!)
30−?: ?=(p.i.q p)
31− q.i.q
32−$(q t.q)
33−```
34−
35−## Syntax
36−
37−Regular: *1-fixed*, then *jogging*.
38−
39−## Discussion
40−
41−The `?-` rune is for a conditional expression in which the type of `p` determines which branch is taken. Usually the type of `p` is a union of other types. There is no default branch.
42−
43−The compiler makes sure that your code neither misses a case of
44−the union, nor includes a double case that isn't there. This is
45−not special handling for `?-`, just a consequence of the
46−semantics of `?:`, which `?-` reduces to.
47−
48−A missing case will throw the `mint-lost` error. An extra case
49−will throw `mint-vain`.
50−
51−## Examples
52−
53−```
54−~zod:dojo> =cor |= vat=?(%a %b)
55− ?- vat
56− %a 20
57− %b 42
58− ==
59−
60−~zod:dojo> (cor %a)
61−20
62−
63−~zod:dojo> (cor %b)
64−42
65−
66−~zod:dojo> (cor %c)
67−! nest-fail
68−```
reference/hoon-expressions/rune/wut/ket.udondeleted−39
@@ -1,39 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'3'
4− title/'?^ "wutket"'
5− ==
6−;>
7−
8−# `?^ "wutket"`
9−
10−`[%wtkt p=wing q=hoon r=hoon]`: branch on whether a wing
11−of the subject is a cell.
12−
13−## Expands to
14−
15−```
16−?:(?=(^ p) q r)
17−```
18−
19−## Syntax
20−
21−Regular: *3-fixed*.
22−
23−## Discussion
24−
25−The type of the wing, `p`, must not be known to be either an atom or a cell, or else you'll get a `mint-vain` error at compile time. `mint-vain` means that one of the `?^` branches, `q` or `r`, is never taken.
26−
27−## Examples
28−
29−```
30−~zod:dojo> ?^(0 1 2)
31−! mint-vain
32−! exit
33−
34−~zod:dojo> ?^(`*`0 1 2)
35−2
36−
37−~zod:dojo> ?^(`*`[1 2] 3 4)
38−3
39−```
reference/hoon-expressions/rune/wut/led.udondeleted−44
@@ -1,44 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'8'
4− title/'?< "wutled"'
5− ==
6−;>
7−
8−# `?< "wutled"`
9−
10−`[%wtgl p=hoon q=hoon]`: negative assertion.
11−
12−## Expands to
13−
14−```
15−?:(p !! q)
16−```
17−
18−## Syntax
19−
20−Regular: *2-fixed*.
21−
22−## Discussion
23−
24−`?<` is used to force a crash when some condition `p` doesn't yield 'no', `%.n`.
25−
26−It can be used for type inference with the `?=` rune, much like the `?>` rune.
27−
28−## Examples
29−
30−```
31−> ?<(=(3 4) %foo)
32−%foo
33−
34−> ?<(=(3 3) %foo)
35−ford: build failed
36−
37−> =a `*`[12 14]
38−
39−> `^`a
40−nest-fail
41−
42−> ?<(?=(@ a) `^`a)
43−[12 14]
44−```
reference/hoon-expressions/rune/wut/lus.udondeleted−63
@@ -1,63 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'5'
4− title/'?+ "wutlus"'
5− ==
6−;>
7−
8−# `?+ "wutlus"`
9−
10−`[%wtls p=wing q=hoon r=(list (pair spec hoon))]`: switch against
11−a union, with a default.
12−
13−## Expands to
14−
15−*Pseudocode*: `a`, `b`, `c`, ... as elements of `r`:
16−
17−```
18−?: ?=(p.a) q.a
19−?: ?=(p.b) q.b
20−?: ?=(p.c) q.c
21−...
22−q
23−```
24−
25−### Compiler macro
26−
27−```
28−|-
29−?. r
30− q
31−?: ?=(p.i.r p)
32− q.i.r
33−$(r t.r)
34−```
35−
36−## Syntax
37−
38−Regular: *2-fixed*, then *jogging*.
39−
40−## Discussion
41−
42−The `?+` rune is for a conditional expression in which the type of `p` determines which branch is taken. Usually the type of `p` is a union of other types. If `p`'s type doesn't match the case for any given branch, the default expression, `q`, is evaluated.
43−
44−If there is a case that is never taken you'll get a `mint-vain` error.
45−
46−## Examples
47−
48−```
49−~zod:dojo> =cor |= vat=?(%a %b)
50− ?+ vat 240
51− %a 20
52− %b 42
53− ==
54−
55−~zod:dojo> (cor %a)
56−20
57−
58−~zod:dojo> (cor %b)
59−42
60−
61−~zod:dojo> (cor %c)
62−240
63−```
reference/hoon-expressions/rune/wut/pad.udondeleted−45
@@ -1,45 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'9'
4− title/'?& "wutpad"'
5− ==
6−;>
7−
8−# `?& "wutpad"`
9−
10−`[%wtpd p=(list hoon)]`: logical AND.
11−
12−## Expands to
13−
14−*Pseudocode*: `a`, `b`, `c`, ... as elements of `p`:
15−
16−```
17−?.(a | ?.(b | ?.(c | ?.(... ?.(z | &)))))
18−```
19−
20−### Compiler macro
21−
22−```
23−|-
24−?~ p
25− &
26−?. i.p
27− |
28−$(p t.p)
29−```
30−
31−## Syntax
32−
33−Regular: *running*.
34−
35−Irregular: `&(foo bar baz)` is `?&(foo bar baz)`.
36−
37−## Examples
38−
39−```
40−~zod:dojo> &(=(6 6) =(42 42))
41−%.y
42−
43−~zod:dojo> &(=(6 7) =(42 43))
44−%.n
45−```
reference/hoon-expressions/rune/wut/sig.udondeleted−33
@@ -1,33 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'13'
4− title/'?~ "wutsig"'
5− ==
6−;>
7−
8−# `?~ "wutsig"`
9−
10−`[%wtsg p=wing q=hoon r=hoon]`: branch on whether a wing of the subject is null.
11−
12−## Expands to
13−
14−```
15−?:(?=($~ p) q r)
16−```
17−
18−## Syntax
19−
20−Regular: *3-fixed*.
21−
22−## Discussion
23−
24−It's bad style to use `?~` to test for any zero atom. Use it only for a true null, `~`.
25−
26−## Examples
27−
28−```
29−~zod:dojo> =foo ""
30−
31−~zod:dojo> ?~(foo 1 2)
32−1
33−```
reference/hoon-expressions/rune/wut/tis.udondeleted−42
@@ -1,42 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'12'
4− title/'?= "wuttis"'
5− ==
6−;>
7−
8−# `?= "wuttis"`
9−
10−`[%wtts p=spec q=wing]`: test pattern match.
11−
12−## Produces
13−
14−`%.y` (yes) if the noun at `q` is in the type of `p`; `%.n` (no) otherwise.
15−
16−## Syntax
17−
18−Regular: *2-fixed*.
19−
20−## Discussion
21−
22−`?=` is not as powerful as it might seem. For instance, it
23−can't generate a loop -- you cannot (and should not) use it to
24−test whether a `*` is a `(list @)`. Nor can it validate atomic
25−auras.
26−
27−Patterns should be as weak as possible. Unpack one layer of
28−union at a time. Don't confirm things the type system knows.
29−
30−For example, when matching from a tagged union for the type `[%foo p=@
31−q=[@ @]]`, the appropriate pattern is `[%foo *]`. You have one
32−question, which is whether the head of the noun is `%foo`.
33−
34−A common error is `find.$`, meaning `p` is not a type.
35−
36−## Examples
37−
38−```
39−~zod:dojo> =bar [%foo %bar %baz]
40−~zod:dojo> ?=([%foo *] bar)
41−%.y
42−```
reference/hoon-expressions/rune/wut/vat.udondeleted−38
@@ -1,38 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'2'
4− title/'?@ "wutvat"'
5− ==
6−;>
7−
8−# `?@ "wutvat"`
9−
10−`[%wtpt p=wing q=hoon r=hoon]`: branch on whether a wing of the subject is an atom.
11−
12−## Expands to
13−
14−```
15−?:(?=(@ p) q r)
16−```
17−
18−## Syntax
19−
20−Regular: *3-fixed*.
21−
22−## Discussion
23−
24−The type of the wing, `p`, must not be known to be either an atom or a cell, or else you'll get a `mint-vain` error at compile time. `mint-vain` means that one of the `?@` branches, `q` or `r`, is never taken.
25−
26−## Examples
27−
28−```
29−~zod:dojo> ?@(0 1 2)
30−! mint-vain
31−! exit
32−
33−~zod:dojo> ?@(`*`0 1 2)
34−1
35−
36−~zod:dojo> ?@(`*`[1 2] 3 4)
37−4
38−```
reference/hoon-expressions/rune/wut/zap.udondeleted−40
@@ -1,40 +0,0 @@
1−:- :~ navhome/'/docs/'
2− next/'true'
3− sort/'11'
4− title/'?! "wutzap"'
5− ==
6−;>
7−
8−# `?! "wutzap"`
9−
10−`[%wtzp p=hoon]`: logical NOT.
11−
12−## Expands to
13−
14−```
15−.=(| p)
16−```
17−
18−Produces the logical NOT of `p`.
19−
20−## Syntax
21−
22−Regular: *1-fixed*.
23−
24−Irregular: `!foo` is `?!(foo)`.
25−
26−## Examples
27−
28−```
29−~zod:dojo> ?!(.=(1 2))
30−%.y
31−
32−~zod:dojo> !&
33−%.n
34−
35−~zod:dojo> !|
36−%.y
37−
38−~zod:dojo> !(gth 5 6)
39−%.y
40−```
reference/hoon-expressions/rune/zap.udon+219−1
@@ -9,4 +9,222 @@
9
9
10## Runes
10## Runes
11
11
12−;list(datapreview "true", classname "runes");
12+;=
13+ ;h3
14+ ;div(id "zapban"): !> "zapban"
15+ ==
16+==
17+
18+`[%zpgr p=hoon]`: wrap a noun in its type.
19+
20+##### Produces
21+
22+A cell whose tail is the product of `p`, and whose head is the static type of `p`.
23+
24+##### Syntax
25+
26+Regular: *1-fixed*.
27+
28+##### Discussion
29+
30+In Hoon, dynamic type is static type compiled at runtime. This type-noun cell is generally called a `vase`.
31+
32+##### Examples
33+
34+```
35+> !>(1)
36+[p=#t/@ud q=1]
37+```
38+
39+If you want just the type value, use a 'type spear'. This is `-:!>`, i.e., the head of the cell produced by `!>`:
40+
41+```
42+> -:!>(1)
43+#t/@ud
44+```
45+
46+;=
47+ ;h3
48+ ;div(id "zapcol"): !: "zapcol"
49+ ==
50+==
51+
52+`[%dbug p=hoon]`: turn on stack trace
53+
54+##### Produces
55+
56+The product of `p` unless `p` crashes, in which case a stack trace is given.
57+
58+##### Syntax
59+
60+Regular: *1-fixed*.
61+
62+```
63+!: p=hoon
64+```
65+
66+##### Discussion
67+
68+`!:` is used to turn on a debugging stack trace option for any code you have in `p`.
69+
70+##### Examples
71+
72+```
73+> ?:(=(0 1) 123 !!)
74+ford: %ride failed to execute:
75+
76+> !: ?:(=(0 1) 123 !!)
77+/~zod/home/~2018.10.15..19.50.06..74af:<[1 5].[1 22]>
78+/~zod/home/~2018.10.15..19.50.06..74af:<[1 19].[1 21]>
79+ford: %ride failed to execute:
80+```
81+
82+;=
83+ ;h3
84+ ;div(id "zapdot"): !. "zapdot"
85+ ==
86+==
87+
88+Turn on stack trace for a subexpression `p`
89+
90+##### Produces
91+
92+The product of `p`. If `p` crashes, no stack trace entries are given for that code.
93+
94+##### Syntax
95+
96+Regular: *1-fixed*.
97+
98+```
99+!. p=hoon
100+```
101+
102+`p` is any Hoon expression.
103+
104+##### Discussion
105+
106+`!.` is used to turn off a debugging stack trace option for any code you have in `p`. This rune can be embedded under a `!:` rune for inner loops of your code that you don't want or need to trace. This is especially useful if a trace overflows the stack.
107+
108+##### Examples
109+
110+```
111+> %.(1 |=(a=@ ^-(@ ?:(=(a 10) !! $(a +(a))))))
112+ford: %ride failed to execute:
113+
114+> !: %.(1 |=(a=@ ^-(@ ?:(=(a 10) !! $(a +(a))))))
115+/~zod/home/~2018.10.15..20.01.21..6b0c:<[1 5].[1 49]>
116+/~zod/home/~2018.10.15..20.01.21..6b0c:<[1 17].[1 47]>
117+/~zod/home/~2018.10.15..20.01.21..6b0c:<[1 22].[1 46]>
118+/~zod/home/~2018.10.15..20.01.21..6b0c:<[1 36].[1 45]>
119+...skipping some lines...
120+/~zod/home/~2018.10.15..20.01.21..6b0c:<[1 17].[1 47]>
121+/~zod/home/~2018.10.15..20.01.21..6b0c:<[1 22].[1 46]>
122+/~zod/home/~2018.10.15..20.01.21..6b0c:<[1 33].[1 35]>
123+ford: %ride failed to execute:
124+
125+> !: %.(1 !.(|=(a=@ ^-(@ ?:(=(a 10) !! $(a +(a)))))))
126+/~zod/home/~2018.10.15..20.01.35..0529:<[1 5].[1 53]>
127+ford: %ride failed to execute:
128+```
129+
130+;=
131+ ;h3
132+ ;div(id "zaptis"): != "zaptis"
133+ ==
134+==
135+
136+`[%zpts p=hoon]`: make the Nock formula for a Hoon expression.
137+
138+##### Produces
139+
140+The Nock generated by `p`.
141+
142+##### Syntax
143+
144+Regular: *1-fixed*.
145+
146+##### Discussion
147+
148+Don't confuse `!=` with a negation, `!`, followed by a test for equality, `=(10 11)`.
149+
150+##### Examples
151+
152+```
153+> !=(20)
154+[1 20]
155+
156+> !=(~zod)
157+[1 0]
158+
159+> !=((add 2 2))
160+[8 [9 3.110.356 0 31] 9 2 [0 4] [7 [0 3] 1 2 2] 0 11]
161+```
162+
163+Don't confuse the `!=` rune with:
164+
165+```
166+> !=(10 11)
167+%.y
168+
169+> !=(10 10)
170+%.n
171+```
172+
173+The syntax difference is that a test for equality takes two subexpressions, and the `!=` rune only one.
174+
175+;=
176+ ;h3
177+ ;div(id "zapwut"): !? "zapwut"
178+ ==
179+==
180+
181+`[%zpwt p=@ q=hoon]`: restrict Hoon version.
182+
183+##### Produces
184+
185+`q`, if `p` is greater than or equal to the Hoon kelvin version.
186+(Versions count down; the current version is 141.)
187+
188+##### Syntax
189+
190+Regular: *2-fixed*.
191+
192+##### Examples
193+
194+```
195+> !?(264 (add 2 2))
196+4
197+
198+> !?(164 (add 2 2))
199+4
200+
201+> !?(64 (add 2 2))
202+! exit
203+```
204+
205+;=
206+ ;h3
207+ ;div(id "zapzap"): !! "zapzap"
208+ ==
209+==
210+
211+`[%zpzp ~]`: crash.
212+
213+##### Produces
214+
215+Nothing. Always crashes, with type `%void`.
216+
217+##### Syntax
218+
219+`!!`
220+
221+##### Discussion
222+
223+`%void` nests in every other type, so you can stub out anything with `!!`.
224+
225+##### Examples
226+
227+```
228+> !!
229+ford: build failed
230+```