These runes modify the subject. (Or more precisely, they evaluate at least one of their subexpressions with a modified subject.)

Overview

Hoon doesn't have variables in the ordinary sense. If you want to bind a name to a value, e.g., a to 12, you do so by pinning 12 to the subject and associating the name with it. This sort of operation is done with the = family of runes.

Let's say you have some old subject p. To 'pin' a value to the head means to modify the subject by repacing it with a cell of [new-value p]. The head of the cell is the new value. So to pin 12 with the face a the new subject would be: [a=12 p].

Of course there are many variations on ways to modify the subject, useful for different situations. Hence the whole family of = runes.

Runes

=> "tisgar"

[%tsgr p=hoon q=hoon]: compose two expressions.

Produces

the product of q, with the product of p taken as the subject.

Syntax

Regular: 2-fixed.

Examples

> =>([a=1 b=2 c=3] b)
2

> =>((add 2 4) [. .])
[6 6]

=| "tisbar"

[%tsbr p=spec q=hoon]: combine a default type value with the subject.

Expands to

=+(*p q)

Syntax

Regular: 2-fixed.

Discussion

The default (or 'bunt') value of p is pinned to the head of the subject. Usually p includes a name for ease of reference.

Speaking more loosely, =| usually "declares a variable" which is "uninitialized," presumably because you'll set it in a loop or similar.

Examples

~zod:dojo> =foo  |=  a=@
                 =|  b=@
                 =-  :(add a b c)
                 c=2
~zod:dojo> (foo 5)
7

=: "tiscol"

[%tscl p=(list (pair wing hoon)) q=hoon]: change multiple legs in the subject.

Expands to

=>(%_(. p) q)

Syntax

Regular: jogging, then 1-fixed.

Discussion

This rune is like =., but for modifying the values of multiple legs of the subject.

Examples

~zod:dojo> =+  a=[b=1 c=2]
           =:  c.a  4
               b.a  3
             ==
           a
[b=3 c=4]

=, "tiscom"

[%tscm p=hoon q=hoon]: expose namespace

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.

Syntax

Regular: 2-fixed.

Examples

With an imported core:

> (sum -7 --7)
-find.sum
[crash message]

> (sum:si -7 --7)
--0

> =,  si  (sum -7 --7)
--0

With a dojo-defined face:

> =/  fan  [bab=2 baz=[3 qux=4]]
  =,  fan
  [bab qux.baz]
[2 4]

=. "tisdot"

[%tsdt p=wing q=hoon r=hoon]: change one leg in the subject.

Expands to

=>(%_(. p q) r)

Syntax

Regular: 3-fixed.

Discussion

Technically the =. rune doesn't change the subject. It creates a new subject just like the old one except for a changed value at p. Note that the mutation uses %_ ("cencab"), so the type at p doesn't change. Trying to change the value type results in a nest-fail.

Examples

> =+  a=[b=1 c=2]
  =.  b.a  3
  a
[b=3 c=2]

> =+  a=[b=1 c=2]
  =.(b.a 3 a)
[b=3 c=2]

> =+  a=[b=1 c=2]
  =.(b.a "hello" a)
nest-fail

=- "tishep"

[%tshp p=hoon q=hoon]: combine a new noun with the subject, inverted.

Expands to

=>([q .] p)

Syntax

Regular: 2-fixed.

Discussion

=- 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.

Examples

~zod:dojo> =foo  |=  a=@
                 =+  b=1
                 =-  (add a b c)
                 c=2
~zod:dojo> (foo 5)
8

=^ "tisket"

[%tskt p=skin q=wing r=hoon s=hoon]: pin the head of a pair; change a leg with the tail.

Expands to

=/(p -.r =.(q +.r s))

Syntax

Regular: 4-fixed.

Discussion

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.

We generally use =^ when we have a state machine with a function, r, that produces a cell, whose head is a result and whose tail is a new state. The head value is given a new name p, and the tail is stuffed back into wherever we stored the old state, q.

This may also remind you of Haskell's State monad.

Examples

The og core is a stateful pseudo-random number generator. We have to change the core state every time we generate a random number, so we use =^:

~zod:dojo> =+  rng=~(. og 420)
           =^  r1  rng  (rads:rng 100)
           =^  r2  rng  (rads:rng 100)
           [r1 r2]
[99 46]

=< "tisgal"

[%tsgl p=hoon q=hoon]: compose two expressions, inverted.

Expands to

=>(q p)

Syntax

Regular: 2-fixed.

Irregular: foo:baz is =<(foo baz).

Discussion

=< is just => backwards.

Examples

~zod:dojo> =<(b [a=1 b=2 c=3])
2

~zod:dojo> =<  b
           [a=1 b=2 c=3]
2

~zod:dojo> b:[a=1 b=2 c=3]
2

~zod:dojo> [. .]:(add 2 4)
[6 6]

=+ "tislus"

[%tsls p=hoon q=hoon]: combine a new noun with the subject.

Expands to

=>([p .] q)

Syntax

Regular: 2-fixed.

Discussion

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.

Loosely speaking, =+ is the simplest way of "declaring a variable."

Examples

=; "tismic"

[%tsmc p=skin q=hoon r=hoon]: combine a named noun with the subject, possibly with type annotation; inverted order.

Expands to

=/(p r q)

Syntax

Regular: 3-fixed.

Discussion

=; is exactly like =/ except that the order of its last two subexpressions is reversed.

Examples

~zod:dojo> =foo  |=  a=@
                 =/   b  1
                 =;   c=@  :(add a b c)
                 2
~zod:dojo> (foo 5)
8

=/ "tisfas"

[%tsfs p=skin q=hoon r=hoon]: combine a named noun with the subject, possibly with type annotation.

Expands to

if p is a name, (e.g. a):

=+(^=(p q) r)

if p is a name with a type (e.g., a=@):

=+(^-(p q) r)

Desugaring

?@  p
  =+  p=q
  r
=+  ^-($=(p.p q.p) q)
r

Syntax

Regular: 3-fixed.

Discussion

p can be either a name or a name=type. If it's just a name, =/ ("tisfas") "declares a type-inferred variable." If it has a type, =/ "declares a type-checked variable."

Examples

~zod:dojo> =foo  |=  a=@
                 =/  b  1
                 =/  c=@  2
                 :(add a b c)
~zod:dojo> (foo 5)
8

=~ "tissig"

[%tssg p=(list hoon)]: compose many expressions.

Produces

The product of the chain composition.

Syntax

Regular: running.

Examples

~zod:dojo> =~  [sub (mul 3 20) (add 10 20)]
      (sub +)
      +(.)
  ==
31

~zod:dojo> =foo =|  n=@
                =<  =~  increment
                        increment
                        increment
                        n
                    ==
                |%
                ++  increment
                  ..increment(n +(n))
                --
~zod:dojo> foo
3

=* "tistar"

[%tstr p=term q=hoon r=hoon]: define a macro.

Produces

r, compiled with a subject in which p is a macro for q.

Syntax

Regular: 3-fixed.

Discussion

The difference between macroing and pinning is that pinning changes the subject, but for macroing the subject noun stays the same. The macro'd expression, q, is recorded in the type information of p. q is calculated every time you use the p macro.

Examples

~zod:dojo>
    =+  a=1
    =*  b  a
    [a b]
[1 1]

~zod:dojo>
    =+  a=1
    =*  b  a
    =.  a  2
    [a b]
[2 2]

=? "tiswut"

[$tswt p=wing q=hoon r=hoon s=hoon]: conditionally change one leg in the subject.

Expands to

=.  p  ?:(q r p)
s

Syntax

Regular: 4-fixed.

Discussion

Use =? to replace the value of leg p with r on condition q. As usual, we are not actually mutating the subject, just creating a new subject with a changed value. The change in value includes a type check against the old subject; the type of r must nest under the type of p.

Examples

> =a 12

> =?(a =(1 1) 22 a)
22

> =?(a =(1 2) 22 a)
12