@@ -4,109 +4,175 @@ weight = 10
4template = "doc.html"
4template = "doc.html"
5aliases = ["docs/reference/hoon-expressions/rune/cen/"]
5aliases = ["docs/reference/hoon-expressions/rune/cen/"]
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.)
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−## Runes
13+These runes reduce to the `%=` rune.
13−### `%_` "cencab"
15+## `%_` "cencab"
15Resolve a wing with changes, preserving type.
17Resolve a wing with changes, preserving type.
17−##### Syntax
19+#### Syntax
19−Regular, tall:
21+One fixed argument, then a variable number of pairs.
24+<tr><th>Form</th><th>Syntax</th></tr>
26+<td>Tall style #1</td>
23 b=wing c=hoon
30 b=wing c=hoon
24 d=wing e=hoon
31 d=wing e=hoon
26 f=wing g=hoon
32 f=wing g=hoon
30−Regular, flat:
36+</tr>
38+<td>Tall style #2</td>
33%_(a=wing b=wing c=hoon, d=wing e=hoon, ...)
58%_(a=wing b=wing c=hoon, d=wing e=hoon, ...)
39[%cncb p=wing q=(list (pair wing hoon))]
71[%cncb p=wing q=(list (pair wing hoon))]
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`.
46−##### Expands to
74+#### Expands to
49^+(a %=(a b c, d e, ...))
77^+(a %=(a b c, d e, ...))
52−##### Discussion
80+#### Semantics
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`.
54−`%_` is different from `%=` because `%=` can change the type of a wing with mutations. `%_` preserves the wing type.
89+`%_` is different from `%=` because `%=` can change the type of a wing with
90+mutations. `%_` preserves the wing type.
56See [how wings are resolved](/docs/hoon/reference/limbs/).
92See [how wings are resolved](/docs/hoon/reference/limbs/).
58−##### Examples
94+#### Examples
61−~zod:dojo> =foo [p=42 q=6]
97+> =foo [p=42 q=6]
63−~zod:dojo> foo(p %baz)
99+> foo(p %baz)
64[p=%baz q=6]
100[p=%baz q=6]
66−~zod:dojo> foo(p [55 99])
102+> foo(p [55 99])
67[p=[55 99] q=6]
103[p=[55 99] q=6]
69−~zod:dojo> %_(foo p %baz)
105+> %_(foo p %baz)
70[p=7.496.034 99]
106[p=7.496.034 99]
72−~zod:dojo> %_(foo p [55 99])
108+> %_(foo p [55 99])
73! nest-fail
109! nest-fail
76−### `%:` "cencol"
114+## `%:` "cencol"
78Call a gate with many arguments.
116Call a gate with many arguments.
80−##### Syntax
118+#### Syntax
82−Regular:
120+One fixed argument, then a variable number of arguments.
123+<tr><th>Form</th><th>Syntax</th></tr>
96[%cncl p=hoon q=(list hoon)]
158[%cncl p=hoon q=(list hoon)]
99−##### Semantics
161+#### Semantics
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]`.
103−##### Discussion
169+#### Discussion
105When `%:` is used in tall-form syntax, the series of expressions after `p` must be terminated with `==`.
171When `%:` is used in tall-form syntax, the series of expressions after `p` must be terminated with `==`.
107−##### Examples
173+#### Examples
110> %: add 22 33 ==
176> %: add 22 33 ==
@@ -123,211 +189,342 @@ When `%:` is used in tall-form syntax, the series of expressions after `p` must
123> %: adder 22 33 44 55 ==
189> %: adder 22 33 44 55 ==
126−> %:(adder 22 33 44 ~)
192+> %:(adder 22 33 44)
130−### `%.` "cendot"
199+---
132−Call a gate (function), inverted.
201+## `%.` "cendot"
134−##### Syntax
203+Call a gate (function), inverted.
136−Regular:
205+#### Syntax
207+Two arguments, fixed.
210+<tr><th>Form</th><th>Syntax</th></tr>
145[%cndt p=hoon q=hoon]
236[%cndt p=hoon q=hoon]
148−##### Semantics
239+#### Semantics
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.
152−##### Expands to
244+#### Expands to
155%-(b=hoon a=hoon)
247%-(b=hoon a=hoon)
158−##### Discussion
250+#### Discussion
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.
162−##### Examples
255+#### Examples
165−~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
258+> =add-triple |=([a=@ b=@ c=@] :(add a b c))
167−~zod:dojo> %.([1 2 3] add-triple)
260+> %.([1 2 3] add-triple)
171−### `%-` "cenhep" {#cenhep}
264+---
173−Call a gate (function).
177−Regular:
266+## `%-` "cenhep" {#cenhep}
179−```hoon
268+Call a gate (function).
273+<tr><th>Form</th><th>Syntax</th></tr>
183−Irregular:
292+<td>Irregular</td>
192[%cnhp p=hoon q=hoon]
304[%cnhp p=hoon q=hoon]
195−##### Semantics
307+#### Semantics
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
199−##### Expands to
313+#### Expands to
205−##### Discussion
319+#### Discussion
207−`%-` is used to call a function; `a` is the function ([`gate`](/docs/hoon/reference/rune/bar#bartis),
321+`%-` is used to call a function; `a` is the function
322+([`gate`](/docs/hoon/reference/rune/bar#bartis), `q` the argument. `%-` is a
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).
323+special case of [`%~` ("censig")](#censig), and a gate is a special case of a
324+[door](/docs/hoon/reference/rune/bar#barcab).
210−##### Examples
326+#### Examples
213−~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
329+> =add-triple |=([a=@ b=@ c=@] :(add a b c))
214−~zod:dojo> (add-triple 1 2 3)
331+> (add-triple 1 2 3)
216−~zod:dojo> %-(add-triple [1 2 3])
334+> %-(add-triple [1 2 3])
220−### `%^` "cenket"
338+---
222−Call gate with triple sample.
340+## `%^` "cenket"
224−##### Syntax
342+Call gate with triple sample.
226−Regular:
344+#### Syntax
346+Four arguments, fixed.
349+<tr><th>Form</th><th>Syntax</th></tr>
229−%^ a=hoon b=hoon c=hoon d=hoon
235[%cnkt p=hoon q=hoon r=hoon s=hoon]
382[%cnkt p=hoon q=hoon r=hoon s=hoon]
239−##### Expands to
385+#### Expands to
242%-(a=hoon [b=hoon c=hoon d=hoon])
388%-(a=hoon [b=hoon c=hoon d=hoon])
245−##### Examples
391+#### Examples
248−~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
394+> =add-triple |=([a=@ b=@ c=@] :(add a b c))
250−~zod:dojo> %^(add-triple 1 2 3)
396+> %^(add-triple 1 2 3)
254−### `%+` "cenlus"
400+---
256−Call gate with a cell sample.
402+## `%+` "cenlus"
258−##### Syntax
404+Call gate with a cell sample.
260−Regular:
406+#### Syntax
408+Three arguments, fixed.
411+<tr><th>Form</th><th>Syntax</th></tr>
263−%+ a=hoon b=hoon c=hoon
269[%cnls p=hoon q=hoon r=hoon]
443[%cnls p=hoon q=hoon r=hoon]
272−##### Semantics
446+#### Semantics
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.
276−##### Expands to
451+#### Expands to
279%-(a=hoon [b=hoon c=hoon])
454%-(a=hoon [b=hoon c=hoon])
282−##### Examples
457+#### Examples
285−~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
460+> =add-triple |=([a=@ b=@ c=@] :(add a b c))
287−~zod:dojo> %+(add-triple 1 [2 3])
462+> %+(add-triple 1 [2 3])
291−### `%~` "censig"
466+---
293−Evaluate an arm in a door.
300−%~ a=wing b=hoon c=hoon
303−Irregular: **variadic**
305−`~(a b c)` is `%~(a b c)`.
306−`~(a b c d e)` is `%~(a b [c d e])`.
311−[%cnsg p=wing q=hoon r=(list hoon)]
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"
318−##### Discussion
470+Evaluate an arm in a door.
474+Three arguments, fixed.
477+<tr><th>Form</th><th>Syntax</th></tr>
505+In the irregular form, `r` may be split into multiple parts. Multiple parts of
506+`r` will be formed into a cell.
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.
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)`.
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)`.
322See also [`|_`](/docs/hoon/reference/rune/bar#barcab).
518See also [`|_`](/docs/hoon/reference/rune/bar#barcab).
324−##### Examples
520+#### Examples
327> =mycore |_ a=@
523> =mycore |_ a=@
328 ++ plus-two (add 2 a)
524 ++ plus-two (add 2 a)
329 ++ double (mul 2 a)
525 ++ double (mul 2 a)
331> ~(plus-two mycore 10)
528> ~(plus-two mycore 10)
@@ -335,34 +532,72 @@ See also [`|_`](/docs/hoon/reference/rune/bar#barcab).
338−### `%*` "centar"
537+## `%*` "centar"
340Evaluate an expression, then resolve a wing with changes.
539Evaluate an expression, then resolve a wing with changes.
342−##### Syntax
541+#### Syntax
344−Regular:
543+Two fixed arguments, then a variable number of pairs.
546+<tr><th>Form</th><th>Syntax</th></tr>
548+<td>Tall style #1</td>
347%* a=wing b=hoon
551%* a=wing b=hoon
348 c=wing d=hoon
552 c=wing d=hoon
349 e=wing f=hoon
553 e=wing f=hoon
351 g=wing h=hoon
555 g=wing h=hoon
561+<td>Tall style #2</td>
581+%*(a b c d, e f, g h)
585+<tr><td>Irregular</td><td>None.</td></tr>
358[%cntr p=wing q=hoon r=(list (pair wing hoon))]
591[%cntr p=wing q=hoon r=(list (pair wing hoon))]
361−##### Semantics
594+#### Semantics
596+A `%*` expression evaluates some arbitrary Hoon expression, `b`, and then
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`.
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`.
365−##### Expands to
600+#### Expands to
@@ -374,7 +609,7 @@ A `%*` expression evaluates some arbitrary Hoon expression, `b`, and then resolv
377−##### Examples
612+#### Examples
380> %*($ add a 2, b 3)
615> %*($ add a 2, b 3)
@@ -398,52 +633,96 @@ A `%*` expression evaluates some arbitrary Hoon expression, `b`, and then resolv
398[a=1 b=7 c=10]
633[a=1 b=7 c=10]
401−### `%=` "centis"
638+## `%=` "centis"
403Resolve a wing with changes.
640Resolve a wing with changes.
405−##### Syntax
642+#### Syntax
407−Regular:
644+One fixed argument, then a variable number of pairs.
647+<tr><th>Form</th><th>Syntax</th></tr>
649+<td>Tall style #1</td>
411 b=wing c=hoon
653 b=wing c=hoon
412 d=wing e=hoon
654 d=wing e=hoon
414 f=wing g=hoon
656 f=wing g=hoon
662+<td>Tall style #2</td>
418−Irregular:
687+<td>Irregular</td>
420−`foo(x 1, y 2, z 3)` is `%=(foo x 1, y 2, z 3)`.
689+<pre>
425[%cnts p=wing q=(list (pair wing hoon))]
699[%cnts p=wing q=(list (pair wing hoon))]
428−##### Semantics
702+#### Semantics
430A `%=` expression resolves a wing of the subject, but with changes made.
704A `%=` expression resolves a wing of the subject, but with changes made.
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.
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.
436−##### Discussion
715+#### Discussion
438−Note that `a` is a wing, not just any expression. Knowing that a function
717+Note that `a` is a wing, not just any expression. Knowing that a function call
439−call `(foo baz)` involves evaluating `foo`, replacing its sample
718+`(foo baz)` involves evaluating `foo`, replacing its sample at slot `+6` with
440−at slot `+6` with `baz`, and then resolving to the `$` limb, you might think
719+`baz`, and then resolving to the `$` limb, you might think `(foo baz)` would
441−`(foo baz)` would mean `%=(foo +6 baz)`.
720+mean `%=(foo +6 baz)`.
443−But it's actually `=+(foo =>(%=(+2 +6 baz) $))`. Even if `foo` is
722+But it's actually `=+(foo =>(%=(+2 +6 baz) $))`. Even if `foo` is a wing, we
444−a wing, we would just be mutating `+6` within the core that defines the
723+would just be mutating `+6` within the core that defines the `foo` arm. Instead
445−`foo` arm. Instead we want to modify the **product** of `foo` -- the gate
724+we want to modify the **product** of `foo` -- the gate -- so we have to pin it
446−-- so we have to pin it into the subject.
725+into the subject.
448Here's that again in tall form:
727Here's that again in tall form:
@@ -455,12 +734,14 @@ Here's that again in tall form:
458−##### Examples
737+#### Examples
461−~zod:dojo> =foo [p=5 q=6]
740+> =foo [p=5 q=6]
462−~zod:dojo> foo(p 42)
742+> foo(p 42)
463[p=42 q=6]
743[p=42 q=6]
464−~zod:dojo> foo(+3 99)
745+> foo(+3 99)