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.)
These runes reduce to the %= rune.
Runes
%_ "cencab"
Resolve a wing with changes, preserving type.
Syntax
Regular, tall:
%_ a=wing
b=wing c=hoon
d=wing e=hoon
...
f=wing g=hoon
==
Regular, flat:
%_(a=wing b=wing c=hoon, d=wing e=hoon, ...)
AST:
[%cncb p=wing q=(list (pair wing hoon))]Semantics
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.
Expands to
^+(a %=(a b c, d e, ...))
Discussion
%_ is different from %= because %= can change the type of a wing with mutations. %_ preserves the wing type.
Examples
~zod:dojo> =foo [p=42 q=6]
~zod:dojo> foo(p %baz)
[p=%baz q=6]
~zod:dojo> foo(p [55 99])
[p=[55 99] q=6]
~zod:dojo> %_(foo p %baz)
[p=7.496.034 99]
~zod:dojo> %_(foo p [55 99])
! nest-fail%: "cencol"
Call a gate with many arguments.
Syntax
Regular:
%: a=hoon
b=hoon
c=hoon
...
d=hoon
==
AST:
[%cncl p=hoon q=(list hoon)]Semantics
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].
Discussion
When %: is used in tall-form syntax, the series of expressions after p must be terminated with ==.
Examples
> %: add 22 33 ==
55
> =adder |= a=*
=+ c=0
|-
?@ a (add a c)
?^ -.a !!
$(c (add -.a c), a +.a)
> %: adder 22 33 44 ==
99
> %: adder 22 33 44 55 ==
154
> %:(adder 22 33 44 ~)
99
%. "cendot"
Call a gate (function), inverted.
Syntax
Regular:
%. a=hoon b=hoon
AST:
[%cndt p=hoon q=hoon]Semantics
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.
Expands to
%-(b=hoon a=hoon)
Discussion
%. is just like %-, but with its subexpressions reversed; the argument comes first, and then the gate.
Examples
~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
~zod:dojo> %.([1 2 3] add-triple)
6%- "cenhep"
Call a gate (function).
Syntax
Regular:
%- a=hoon b=hoon
Irregular:
(a=hoon b=hoon)
AST:
[%cnhp p=hoon q=hoon]Semantics
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.
Expands to
%~($ a b)
Discussion
%- is used to call a function; a is the function (gate,
q the argument. %- is a special case of %~ ("censig"), and a gate is a special case of a door.
Examples
~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
~zod:dojo> (add-triple 1 2 3)
6
~zod:dojo> %-(add-triple [1 2 3])
6%^ "cenket"
Call gate with triple sample.
Syntax
Regular:
%^ a=hoon b=hoon c=hoon d=hoon
AST:
[%cnkt p=hoon q=hoon r=hoon s=hoon]Expands to
%-(a=hoon [b=hoon c=hoon d=hoon])
Examples
~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
~zod:dojo> %^(add-triple 1 2 3)
6%+ "cenlus"
Call gate with a cell sample.
Syntax
Regular:
%+ a=hoon b=hoon c=hoon
AST:
[%cnls p=hoon q=hoon r=hoon]Semantics
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.
Expands to
%-(a=hoon [b=hoon c=hoon])
Examples
~zod:dojo> =add-triple |=([a=@ b=@ c=@] :(add a b c))
~zod:dojo> %+(add-triple 1 [2 3])
6%~ "censig"
Evaluate an arm in a door.
Syntax
Regular: 3-fixed
%~ a=wing b=hoon c=hoon
Irregular: variadic
~(a b c) is %~(a b c).
~(a b c d e) is %~(a b [c d e]).
AST:
[%cnsg p=wing q=hoon r=(list hoon)]Semantics
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.
Discussion
%~ 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).
See also |_.
Examples
> =mycore |_ a=@
++ plus-two (add 2 a)
++ double (mul 2 a)
--
> ~(plus-two mycore 10)
12
> ~(double mycore 10)
20
%* "centar"
Evaluate an expression, then resolve a wing with changes.
Syntax
Regular:
%* a=wing b=hoon
c=wing d=hoon
e=wing f=hoon
...
g=wing h=hoon
==
AST:
[%cntr p=wing q=hoon r=(list (pair wing hoon))]Semantics
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.
Expands to
=+ b=hoon
%= a=wing
c=wing d=hoon
e=wing f=hoon
...
g=wing h=hoon
==
Examples
> %*($ add a 2, b 3)
5
> %*(b [a=[12 14] b=[c=12 d=44]] c 11)
[c=11 d=44]
> %*(b [a=[12 14] b=[c=12 d=44]] c 11, d 33)
[c=11 d=33]
> =foo [a=1 b=2 c=3 d=4]
> %*(+ foo c %hello, d %world)
[b=2 c=%hello d=%world]
> =+(foo=[a=1 b=2 c=3] foo(b 7, c 10))
[a=1 b=7 c=10]
> %*(foo [foo=[a=1 b=2 c=3]] b 7, c 10)
[a=1 b=7 c=10]%= "centis"
Resolve a wing with changes.
Syntax
Regular:
%= a=wing
b=wing c=hoon
d=wing e=hoon
...
f=wing g=hoon
==
Irregular:
foo(x 1, y 2, z 3) is %=(foo x 1, y 2, z 3).
AST:
[%cnts p=wing q=(list (pair wing hoon))]Semantics
A %= expression resolves a wing of the subject, but with changes made.
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.
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.
Discussion
Note that a is a wing, not just any expression. Knowing that a function
call (foo baz) involves evaluating foo, replacing its sample
at slot +6 with baz, and then resolving to the $ limb, you might think
(foo baz) would mean %=(foo +6 baz).
But it's actually =+(foo =>(%=(+2 +6 baz) $)). Even if foo is
a wing, we would just be mutating +6 within the core that defines the
foo arm. Instead we want to modify the product of foo -- the gate
-- so we have to pin it into the subject.
Here's that again in tall form:
=+ foo
=> %= +2
+6 baz
==
$
Examples
~zod:dojo> =foo [p=5 q=6]
~zod:dojo> foo(p 42)
[p=42 q=6]
~zod:dojo> foo(+3 99)
[p=5 99]