@@ -4,109 +4,175 @@ weight = 10
44template = "doc.html"
55aliases = ["docs/reference/hoon-expressions/rune/cen/"]
66+++
7−The `%` family of runes is used for making 'function calls' in Hoon. To be more precise, these runes evaluate the `$` arm in cores, usually after modifying the sample. (The default sample is replaced with the input values given in the call.)
87
9−These runes reduce to the `%=` rune.
8+The `%` family of runes is used for making 'function calls' in Hoon. To be more
9+precise, these runes evaluate the `$` arm in cores, usually after modifying the
10+sample. (The default sample is replaced with the input values given in the
11+call.)
1012
11−## Runes
13+These runes reduce to the `%=` rune.
1214
13−### `%_` "cencab"
15+## `%_` "cencab"
1416
1517Resolve a wing with changes, preserving type.
1618
17−##### Syntax
19+#### Syntax
1820
19−Regular, tall:
21+One fixed argument, then a variable number of pairs.
2022
21−```hoon
23+<table>
24+<tr><th>Form</th><th>Syntax</th></tr>
25+<tr>
26+<td>Tall style #1</td>
27+<td>
28+<pre>
2229%_ a=wing
2330 b=wing c=hoon
2431 d=wing e=hoon
25− ...
2632 f=wing g=hoon
2733==
28−```
29−
30−Regular, flat:
31−
32−```hoon
34+</pre>
35+</td>
36+</tr>
37+<tr>
38+<td>Tall style #2</td>
39+<td>
40+<pre>
41+%_ a=wing
42+ b=wing
43+ c=hoon
44+::
45+ d=wing
46+ e=hoon
47+::
48+ f=wing
49+ g=hoon
50+==
51+</pre>
52+</td>
53+</tr>
54+<tr>
55+<td>Wide</td>
56+<td>
57+<pre>
3358%_(a=wing b=wing c=hoon, d=wing e=hoon, ...)
34−```
59+</pre>
60+</td>
61+</tr>
62+<tr>
63+<td>Irregular</td>
64+<td>None.</td>
65+</tr>
66+</table>
3567
36−AST:
68+#### AST
3769
38−```
70+```hoon
3971[%cncb p=wing q=(list (pair wing hoon))]
4072```
4173
42−##### Semantics
43−
44−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`.
45−
46−##### Expands to
74+#### Expands to
4775
4876```hoon
4977^+(a %=(a b c, d e, ...))
5078```
5179
52−##### Discussion
80+#### Semantics
81+
82+A `%_` expression resolves to the value of the subject at wing `a`, but modified
83+according to a series of changes: `b` is replaced with the product of `c`, `d`
84+with the product of `e`, and so on. At compile time a type check is performed to
85+ensure that the resulting value is of the same type as `a`.
5386
54−`%_` is different from `%=` because `%=` can change the type of a wing with mutations. `%_` preserves the wing type.
87+#### Discussion
88+
89+`%_` is different from `%=` because `%=` can change the type of a wing with
90+mutations. `%_` preserves the wing type.
5591
5692See [how wings are resolved](/docs/hoon/reference/limbs/).
5793
58−##### Examples
94+#### Examples
5995
6096```
61−~zod:dojo> =foo [p=42 q=6]
97+> =foo [p=42 q=6]
6298
63−~zod:dojo> foo(p %baz)
99+> foo(p %baz)
64100[p=%baz q=6]
65101
66−~zod:dojo> foo(p [55 99])
102+> foo(p [55 99])
67103[p=[55 99] q=6]
68104
69−~zod:dojo> %_(foo p %baz)
105+> %_(foo p %baz)
70106[p=7.496.034 99]
71107
72−~zod:dojo> %_(foo p [55 99])
108+> %_(foo p [55 99])
73109! nest-fail
74110```
75111
76−### `%:` "cencol"
112+---
113+
114+## `%:` "cencol"
77115
78116Call a gate with many arguments.
79117
80−##### Syntax
118+#### Syntax
81119
82−Regular:
120+One fixed argument, then a variable number of arguments.
83121
84−```hoon
122+<table>
123+<tr><th>Form</th><th>Syntax</th></tr>
124+<tr>
125+<td>Tall</td>
126+<td>
127+<pre>
85128%: a=hoon
86129 b=hoon
87130 c=hoon
88131 ...
89132 d=hoon
90133==
91−```
92−
93−AST:
134+</pre>
135+</td>
136+</tr>
137+<tr>
138+<td>Wide</td>
139+<td>
140+<pre>
141+%:(a b c d)
142+</pre>
143+</td>
144+</tr>
145+<tr>
146+<td>Irregular</td>
147+<td>
148+<pre>
149+(a b c d)
150+</pre>
151+</td>
152+</tr>
153+</table>
154+
155+#### AST
94156
95−```
157+```hoon
96158[%cncl p=hoon q=(list hoon)]
97159```
98160
99−##### Semantics
161+#### Semantics
100162
101−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]`.
163+A `%:` expression calls a gate with many arguments. `a` is the gate to be
164+called, and `b` through `d` are the arguments. If there is only one
165+subexpression after `a`, its product is the sample. Otherwise, a single argument
166+is constructed by evaluating all of `b` through `d` -- however many
167+subexpressions there are -- and putting the result in a cell: `[b c ... d]`.
102168
103−##### Discussion
169+#### Discussion
104170
105171When `%:` is used in tall-form syntax, the series of expressions after `p` must be terminated with `==`.
106172
107−##### Examples
173+#### Examples
108174
109−```hoon
175+```
110176> %: add 22 33 ==
11117755
112178
@@ -123,211 +189,342 @@ When `%:` is used in tall-form syntax, the series of expressions after `p` must
123189> %: adder 22 33 44 55 ==
124190154
125191
126−> %:(adder 22 33 44 ~)
192+> %:(adder 22 33 44)
193+99
194+
195+> (adder 22 33 44)
12719699
128197```
129198
130−### `%.` "cendot"
199+---
131200
132−Call a gate (function), inverted.
201+## `%.` "cendot"
133202
134−##### Syntax
203+Call a gate (function), inverted.
135204
136−Regular:
205+#### Syntax
206+
207+Two arguments, fixed.
208+
209+<table>
210+<tr><th>Form</th><th>Syntax</th></tr>
211+<tr>
212+<td>Tall</td>
213+<td>
214+<pre>
215+%. a b
216+</pre>
217+</td>
218+</tr>
219+<tr>
220+<td>Wide</td>
221+<td>
222+<pre>
223+%.(a b)
224+</pre>
225+</td>
226+</tr>
227+<tr>
228+<td>Irregular</td>
229+<td>None.</td>
230+</tr>
231+</table>
232+
233+#### AST
137234
138235```hoon
139−%. a=hoon b=hoon
140−```
141−
142−AST:
143−
144−```
145236[%cndt p=hoon q=hoon]
146237```
147238
148−##### Semantics
239+#### Semantics
149240
150−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.
241+The `%.` rune is for evaluating the `$` arm of a gate, i.e., calling a function.
242+`a` is for the desired sample value (i.e., input value), and `b` is the gate.
151243
152−##### Expands to
244+#### Expands to
153245
154246```hoon
155247%-(b=hoon a=hoon)
156248```
157249
158−##### Discussion
250+#### Discussion
159251
160−`%.` is just like `%-`, but with its subexpressions reversed; the argument comes first, and then the gate.
252+`%.` is just like `%-`, but with its subexpressions reversed; the argument comes
253+first, and then the gate.
161254
162−##### Examples
255+#### Examples
163256
164257```
165−~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
258+> =add-triple |=([a=@ b=@ c=@] :(add a b c))
166259
167−~zod:dojo> %.([1 2 3] add-triple)
260+> %.([1 2 3] add-triple)
1682616
169262```
170263
171−### `%-` "cenhep" {#cenhep}
172−
173−Call a gate (function).
174−
175−##### Syntax
264+---
176265
177−Regular:
266+## `%-` "cenhep" {#cenhep}
178267
179−```hoon
180−%- a=hoon b=hoon
181−```
268+Call a gate (function).
182269
183−Irregular:
270+#### Syntax
271+
272+<table>
273+<tr><th>Form</th><th>Syntax</th></tr>
274+<tr>
275+<td>Tall</td>
276+<td>
277+<pre>
278+%- a
279+b
280+</pre>
281+</td>
282+</tr>
283+<tr>
284+<td>Wide</td>
285+<td>
286+<pre>
287+%-(a b)
288+</pre>
289+</td>
290+</tr>
291+<tr>
292+<td>Irregular</td>
293+<td>
294+<pre>
295+(a b)
296+</pre>
297+</td>
298+</tr>
299+</table>
300+
301+#### AST
184302
185303```hoon
186−(a=hoon b=hoon)
187−```
188−
189−AST:
190−
191−```
192304[%cnhp p=hoon q=hoon]
193305```
194306
195−##### Semantics
307+#### Semantics
196308
197−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.
309+This rune is for evaluating the `$` arm of a gate, i.e., calling a gate as a
310+function. `a` is the gate, and `b` is the desired sample value (i.e., input
311+value) for the gate.
198312
199−##### Expands to
313+#### Expands to
200314
201315```hoon
202316%~($ a b)
203317```
204318
205−##### Discussion
319+#### Discussion
206320
207−`%-` is used to call a function; `a` is the function ([`gate`](/docs/hoon/reference/rune/bar#bartis),
208−`q` the argument. `%-` is a special case of [`%~` ("censig")](#censig), and a gate is a special case of a [door](/docs/hoon/reference/rune/bar#barcab).
321+`%-` is used to call a function; `a` is the function
322+([`gate`](/docs/hoon/reference/rune/bar#bartis), `q` the argument. `%-` is a
323+special case of [`%~` ("censig")](#censig), and a gate is a special case of a
324+[door](/docs/hoon/reference/rune/bar#barcab).
209325
210−##### Examples
326+#### Examples
211327
212328```
213−~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
214−~zod:dojo> (add-triple 1 2 3)
329+> =add-triple |=([a=@ b=@ c=@] :(add a b c))
330+
331+> (add-triple 1 2 3)
2153326
216−~zod:dojo> %-(add-triple [1 2 3])
333+
334+> %-(add-triple [1 2 3])
2173356
218336```
219337
220−### `%^` "cenket"
338+---
221339
222−Call gate with triple sample.
340+## `%^` "cenket"
223341
224−##### Syntax
342+Call gate with triple sample.
225343
226−Regular:
344+#### Syntax
345+
346+Four arguments, fixed.
347+
348+<table>
349+<tr><th>Form</th><th>Syntax</th></tr>
350+<tr>
351+<td>Tall</td>
352+<td>
353+<pre>
354+%^ a
355+ b
356+ c
357+d
358+</pre>
359+</td>
360+</tr>
361+<tr>
362+<td>Wide</td>
363+<td>
364+<pre>
365+%^(a b c d)
366+</pre>
367+</td>
368+</tr>
369+<tr>
370+<td>Irregular</td>
371+<td>
372+<pre>
373+(a b c d)
374+</pre>
375+</td>
376+</tr>
377+</table>
378+
379+#### AST
227380
228381```hoon
229−%^ a=hoon b=hoon c=hoon d=hoon
230−```
231−
232−AST:
233−
234−```
235382[%cnkt p=hoon q=hoon r=hoon s=hoon]
236383```
237384
238−
239−##### Expands to
385+#### Expands to
240386
241387```hoon
242388%-(a=hoon [b=hoon c=hoon d=hoon])
243389```
244390
245−##### Examples
391+#### Examples
246392
247393```
248−~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
394+> =add-triple |=([a=@ b=@ c=@] :(add a b c))
249395
250−~zod:dojo> %^(add-triple 1 2 3)
396+> %^(add-triple 1 2 3)
2513976
252398```
253399
254−### `%+` "cenlus"
400+---
255401
256−Call gate with a cell sample.
402+## `%+` "cenlus"
257403
258−##### Syntax
404+Call gate with a cell sample.
259405
260−Regular:
406+#### Syntax
407+
408+Three arguments, fixed.
409+
410+<table>
411+<tr><th>Form</th><th>Syntax</th></tr>
412+<tr>
413+<td>Tall</td>
414+<td>
415+<pre>
416+%+ a
417+ b
418+c
419+</pre>
420+</td>
421+</tr>
422+<tr>
423+<td>Wide</td>
424+<td>
425+<pre>
426+%+(a b c)
427+</pre>
428+</td>
429+</tr>
430+<tr>
431+<td>Irregular</td>
432+<td>
433+<pre>
434+(a b c)
435+</pre>
436+</td>
437+</tr>
438+</table>
439+
440+#### AST
261441
262442```hoon
263−%+ a=hoon b=hoon c=hoon
264−```
265−
266−AST:
267−
268−```
269443[%cnls p=hoon q=hoon r=hoon]
270444```
271445
272−##### Semantics
446+#### Semantics
273447
274−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.
448+A `%+` expression is for calling a gate with a cell sample. `a` is the gate to
449+be called, `b` is for the head of the sample, and `c` is for the sample tail.
275450
276−##### Expands to
451+#### Expands to
277452
278453```hoon
279454%-(a=hoon [b=hoon c=hoon])
280455```
281456
282−##### Examples
457+#### Examples
283458
284459```
285−~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
460+> =add-triple |=([a=@ b=@ c=@] :(add a b c))
286461
287−~zod:dojo> %+(add-triple 1 [2 3])
462+> %+(add-triple 1 [2 3])
2884636
289464```
290465
291−### `%~` "censig"
292−
293−Evaluate an arm in a door.
294−
295−##### Syntax
296−
297−Regular: **3-fixed**
298−
299−```hoon
300−%~ a=wing b=hoon c=hoon
301−```
302−
303−Irregular: **variadic**
304−
305−`~(a b c)` is `%~(a b c)`.
306−`~(a b c d e)` is `%~(a b [c d e])`.
307−
308−AST:
309−
310−```
311−[%cnsg p=wing q=hoon r=(list hoon)]
312−```
313−
314−##### Semantics
466+---
315467
316−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.
468+## `%~` "censig"
317469
318−##### Discussion
470+Evaluate an arm in a door.
319471
320−`%~` 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)`.
472+#### Syntax
473+
474+Three arguments, fixed.
475+
476+<table>
477+<tr><th>Form</th><th>Syntax</th></tr>
478+<tr>
479+<td>Tall</td>
480+<td>
481+<pre>
482+%~ p q
483+r
484+</pre>
485+</td>
486+</tr>
487+<tr>
488+<td>Wide</td>
489+<td>
490+<pre>
491+%~(p q r)
492+</pre>
493+</td>
494+</tr>
495+<tr>
496+<td>Irregular</td>
497+<td>
498+<pre>
499+~(p q r1 r2 rn)
500+</pre>
501+</td>
502+</tr>
503+</table>
504+
505+In the irregular form, `r` may be split into multiple parts. Multiple parts of
506+`r` will be formed into a cell.
507+
508+#### Semantics
509+
510+A `%~` expression evaluates the arm of a door (i.e., a core with a sample). `a`
511+is a wing that resolves to the arm from within the door in question. `b` is the
512+door itself. `c` is the sample of the door.
513+
514+#### Discussion
515+
516+`%~` 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)`.
321517
322518See also [`|_`](/docs/hoon/reference/rune/bar#barcab).
323519
324−##### Examples
520+#### Examples
325521
326−```hoon
522+```
327523> =mycore |_ a=@
328524 ++ plus-two (add 2 a)
329525 ++ double (mul 2 a)
330526 --
527+
331528> ~(plus-two mycore 10)
33252912
333530
@@ -335,34 +532,72 @@ See also [`|_`](/docs/hoon/reference/rune/bar#barcab).
33553220
336533```
337534
338−### `%*` "centar"
535+---
536+
537+## `%*` "centar"
339538
340539Evaluate an expression, then resolve a wing with changes.
341540
342−##### Syntax
541+#### Syntax
343542
344−Regular:
543+Two fixed arguments, then a variable number of pairs.
345544
346−```hoon
545+<table>
546+<tr><th>Form</th><th>Syntax</th></tr>
547+<tr>
548+<td>Tall style #1</td>
549+<td>
550+<pre>
347551%* a=wing b=hoon
348552 c=wing d=hoon
349553 e=wing f=hoon
350554 ...
351555 g=wing h=hoon
352556==
353−```
354−
355−AST:
557+</pre>
558+</td>
559+</tr>
560+<tr>
561+<td>Tall style #2</td>
562+<td>
563+<pre>
564+%* a=wing b=hoon
565+ c=wing
566+ d=hoon
567+::
568+ e=wing
569+ f=hoon
570+::
571+ g=wing
572+ h=hoon
573+==
574+</pre>
575+</td>
576+</tr>
577+<tr>
578+<td>Wide</td>
579+<td>
580+<pre>
581+%*(a b c d, e f, g h)
582+</pre>
583+</td>
584+</tr>
585+<tr><td>Irregular</td><td>None.</td></tr>
586+</table>
587+
588+#### AST
356589
357−```
590+```hoon
358591[%cntr p=wing q=hoon r=(list (pair wing hoon))]
359592```
360593
361−##### Semantics
594+#### Semantics
362595
363−A `%*` expression evaluates some arbitrary Hoon expression, `b`, and then resolves a wing of that result, with changes. `a` is the wing to be resolved, and one or more changes is defined by the subexpressions after `b`.
596+A `%*` expression evaluates some arbitrary Hoon expression, `b`, and then
597+resolves a wing of that result, with changes. `a` is the wing to be resolved,
598+and one or more changes is defined by the subexpressions after `b`.
364599
365−##### Expands to
600+#### Expands to
366601
367602```hoon
368603=+ b=hoon
@@ -374,7 +609,7 @@ A `%*` expression evaluates some arbitrary Hoon expression, `b`, and then resolv
374609==
375610```
376611
377−##### Examples
612+#### Examples
378613
379614```
380615> %*($ add a 2, b 3)
@@ -398,52 +633,96 @@ A `%*` expression evaluates some arbitrary Hoon expression, `b`, and then resolv
398633[a=1 b=7 c=10]
399634```
400635
401−### `%=` "centis"
636+---
637+
638+## `%=` "centis"
402639
403640Resolve a wing with changes.
404641
405−##### Syntax
642+#### Syntax
406643
407−Regular:
644+One fixed argument, then a variable number of pairs.
408645
409−```hoon
646+<table>
647+<tr><th>Form</th><th>Syntax</th></tr>
648+<tr>
649+<td>Tall style #1</td>
650+<td>
651+<pre>
410652%= a=wing
411653 b=wing c=hoon
412654 d=wing e=hoon
413655 ...
414656 f=wing g=hoon
415657==
416−```
417−
418−Irregular:
419−
420−`foo(x 1, y 2, z 3)` is `%=(foo x 1, y 2, z 3)`.
421−
422−AST:
658+</pre>
659+</td>
660+</tr>
661+<tr>
662+<td>Tall style #2</td>
663+<td>
664+<pre>
665+%= a=wing
666+ b=wing
667+ c=hoon
668+::
669+ d=wing
670+ e=hoon
671+::
672+ f=wing
673+ g=hoon
674+==
675+</pre>
676+</td>
677+</tr>
678+<tr>
679+<td>Wide</td>
680+<td>
681+<pre>
682+%=(a b c, d e, f g)
683+</pre>
684+</td>
685+</tr>
686+<tr>
687+<td>Irregular</td>
688+<td>
689+<pre>
690+a(b c, d e, f g)
691+</pre>
692+</td>
693+</tr>
694+</table>
695+
696+#### AST
423697
424−```
698+```hoon
425699[%cnts p=wing q=(list (pair wing hoon))]
426700```
427701
428−##### Semantics
702+#### Semantics
429703
430704A `%=` expression resolves a wing of the subject, but with changes made.
431705
432−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.
706+If `a` resolves to a leg, a series of changes are made to wings of that leg
707+(`b`, `d`, and `f` above are replaced with the respective products of `c`, `e`,
708+and `g` above). The modified leg is returned.
433709
434−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.
710+If `a` resolves to an arm, a series of changes are made to wings of the parent
711+core of that arm. (Again, `b`, `d`, and `f` are replaced with the respective
712+products of `c`, `e`, and `g`.) The arm is computed with the modified core as
713+the subject, and the product is returned.
435714
436−##### Discussion
715+#### Discussion
437716
438−Note that `a` is a wing, not just any expression. Knowing that a function
439−call `(foo baz)` involves evaluating `foo`, replacing its sample
440−at slot `+6` with `baz`, and then resolving to the `$` limb, you might think
441−`(foo baz)` would mean `%=(foo +6 baz)`.
717+Note that `a` is a wing, not just any expression. Knowing that a function call
718+`(foo baz)` involves evaluating `foo`, replacing its sample at slot `+6` with
719+`baz`, and then resolving to the `$` limb, you might think `(foo baz)` would
720+mean `%=(foo +6 baz)`.
442721
443−But it's actually `=+(foo =>(%=(+2 +6 baz) $))`. Even if `foo` is
444−a wing, we would just be mutating `+6` within the core that defines the
445−`foo` arm. Instead we want to modify the **product** of `foo` -- the gate
446−-- so we have to pin it into the subject.
722+But it's actually `=+(foo =>(%=(+2 +6 baz) $))`. Even if `foo` is a wing, we
723+would just be mutating `+6` within the core that defines the `foo` arm. Instead
724+we want to modify the **product** of `foo` -- the gate -- so we have to pin it
725+into the subject.
447726
448727Here's that again in tall form:
449728
@@ -455,12 +734,14 @@ Here's that again in tall form:
455734 $
456735```
457736
458−##### Examples
737+#### Examples
459738
460739```
461−~zod:dojo> =foo [p=5 q=6]
462−~zod:dojo> foo(p 42)
740+> =foo [p=5 q=6]
741+
742+> foo(p 42)
463743[p=42 q=6]
464−~zod:dojo> foo(+3 99)
744+
745+> foo(+3 99)
465746[p=5 99]
466747```