@@ -4,127 +4,254 @@ weight = 5
44template = "doc.html"
55+++
66
7−These runes modify the subject. (Or more precisely, they
7+These runes modify the subject. (Or more precisely, they
88evaluate at least one of their subexpressions with a modified subject.)
99
1010## Overview
1111
12−Hoon doesn't have variables in the ordinary sense. If you want to bind a name
12+Hoon doesn't have variables in the ordinary sense. If you want to bind a name
1313to a value, e.g., `a` to `12`, you do so by pinning `12` to the subject and
14−associating the name with it. This sort of operation is done with the `=`
14+associating the name with it. This sort of operation is done with the `=`
1515family of runes.
1616
17−Let's say you have some old subject `p`. To 'pin' a value to the head means to
18−modify the subject by repacing it with a cell of `[new-value p]`. The head of
19−the cell is the new value. So to pin `12` with the face `a` the new subject
17+Let's say you have some old subject `p`. To 'pin' a value to the head means to
18+modify the subject by repacing it with a cell of `[new-value p]`. The head of
19+the cell is the new value. So to pin `12` with the face `a` the new subject
2020would be: `[a=12 p]`.
2121
2222Of course there are many variations on ways to modify the subject, useful for
23−different situations. Hence the whole family of `=` runes.
23+different situations. Hence the whole family of `=` runes.
2424
25−## Runes
25+---
2626
27−### `=>` "tisgar"
27+## `=>` "tisgar"
2828
29−`[%tsgr p=hoon q=hoon]`: compose two expressions.
29+Compose two expressions.
3030
31−##### Produces
31+#### Syntax
3232
33−the product of `q`, with the product of `p` taken as the subject.
33+Two arguments, fixed.
3434
35−##### Syntax
35+Tall form:
3636
37−Regular: **2-fixed**.
37+```hoon
38+=> p
39+q
40+```
3841
39−##### Examples
42+Wide form:
43+
44+```hoon
45+=>(p q)
46+```
47+
48+Irregular form:
49+
50+None.
51+
52+#### AST
53+
54+```hoon
55+[%tsgr p=hoon q=hoon]
56+```
57+
58+#### Produces
59+
60+the product of `q`, with the product of `p` taken as the subject.
61+
62+#### Examples
4063
4164```
4265> =>([a=1 b=2 c=3] b)
43662
4467
68+> => 9 .
69+9
70+
4571> =>((add 2 4) [. .])
4672[6 6]
73+
74+> =>
75+ |%
76+ ++ foo
77+ |= [a=@ b=@]
78+ [b a]
79+ --
80+ (foo 42 27)
81+[27 42]
4782```
4883
49−### `=|` "tisbar"
84+---
85+
86+## `=|` "tisbar"
87+
88+Combine a default type value ("bunt value") with the subject.
89+
90+#### Syntax
91+
92+Two arguments, fixed.
93+
94+Tall form:
95+
96+```hoon
97+=| p
98+q
99+```
50100
101+Wide form:
51102
52−`[%tsbr p=spec q=hoon]`: combine a default type value with the subject.
103+```hoon
104+=|(p q)
105+```
106+
107+Irregular form:
108+
109+None.
110+
111+#### AST
112+
113+```hoon
114+[%tsbr p=spec q=hoon]
115+```
53116
54−##### Expands to
117+#### Expands to
55118
56119```hoon
57120=+(*p q)
58121```
59122
60−##### Syntax
123+#### Discussion
61124
62−Regular: **2-fixed**.
125+The default (or 'bunt') value of `p` is pinned to the head of the subject.
126+Usually `p` includes a name for ease of reference.
63127
64−##### Discussion
128+Speaking more loosely, `=|` usually "declares a variable" which is
129+"uninitialized," presumably because you'll set it in a loop or similar.
65130
66−The default (or 'bunt') value of `p` is pinned to the head of the subject. Usually `p` includes a name for ease of reference.
131+#### Examples
67132
68−Speaking more loosely, `=|` usually "declares a variable" which is "uninitialized," presumably because you'll set it in a loop or similar.
133+```
134+> =| a=@ud a
135+0
136+
137+> =| a=[@t @t @t] a
138+['' '' '']
139+```
140+
141+---
142+
143+## `=:` "tiscol"
69144
70−##### Examples
145+Change multiple legs in the subject.
71146
147+#### Syntax
148+
149+Two arguments: the first a variable number of pairs, the second is fixed.
150+
151+Tall form:
152+
153+```hoon
154+=: p1a p1b
155+ p2a p2b
156+ p3a p3b
157+ ==
158+q
72159```
73−~zod:dojo> =foo |= a=@
74− =| b=@
75− =- :(add a b c)
76− c=2
77−~zod:dojo> (foo 5)
78−7
160+
161+Wide form:
162+
163+```hoon
164+=:(p1a p1b, p2a p2b, p3a p3b q)
79165```
80166
81−### `=:` "tiscol"
167+Irregular form:
82168
83−`[%tscl p=(list (pair wing hoon)) q=hoon]`: change multiple legs in the subject.
169+None.
84170
85−##### Expands to
171+#### AST
86172
87173```hoon
88−=>(%_(. p) q)
174+[%tscl p=(list (pair wing hoon)) q=hoon]
89175```
90176
91−##### Syntax
177+#### Expands to
92178
93−Regular: **jogging**, then **1-fixed**.
179+```hoon
180+=>(%_(. p) q)
181+```
94182
95−##### Discussion
183+#### Discussion
96184
97185This rune is like `=.`, but for modifying the values of multiple legs of the subject.
98186
99−##### Examples
187+#### Examples
100188
101189```
102−~zod:dojo> =+ a=[b=1 c=2]
103− =: c.a 4
104− b.a 3
105− ==
106− a
190+> =+ a=[b=1 c=2]
191+ =: c.a 4
192+ b.a 3
193+ ==
194+ a
107195[b=3 c=4]
108196```
109197
110−### `=,` "tiscom"
198+---
199+
200+## `=,` "tiscom"
201+
202+Expose namespace.
203+
204+#### Syntax
205+
206+Two arguments, fixed.
207+
208+Tall form:
209+
210+```hoon
211+=, p
212+q
213+```
214+
215+Wide form:
216+
217+```hoon
218+=,(p q)
219+```
111220
112−`[%tscm p=hoon q=hoon]`: expose namespace
221+Irregular form:
113222
114−`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.
223+None.
115224
116−##### Syntax
225+#### AST
117226
118−Regular: **2-fixed**.
227+```hoon
228+[%tscm p=hoon q=hoon]
229+```
119230
120−##### Examples
231+#### Produces
232+
233+`p` evaluates to a noun with some namespace. From within `q` you may access
234+`p`'s names without a wing path (i.e., you can use face `b` rather than `b.p`).
235+
236+#### Discussion
237+
238+This is especially useful for calling arms from an imported library core or for
239+calling arms from a stdlib core repeatedly. For example, JSON reparsers like
240+`so:dejs:format` and `of:dejs:format` can be called as `so` and `of` after
241+doing:
242+
243+```hoon
244+=, dejs:format
245+```
246+
247+#### Examples
121248
122249With an imported core:
123250
124251```
125252> (sum -7 --7)
126253-find.sum
127−[crash message]
254+dojo: hoon expression failed
128255
129256> (sum:si -7 --7)
130257--0
@@ -142,26 +269,53 @@ With a dojo-defined face:
142269[2 4]
143270```
144271
145−### `=.` "tisdot"
272+---
273+
274+## `=.` "tisdot"
275+
276+Change one leg in the subject.
146277
147−`[%tsdt p=wing q=hoon r=hoon]`: change one leg in the subject.
278+#### Syntax
148279
149−##### Expands to
280+Three arguments, fixed.
281+
282+Tall form:
150283
151284```hoon
152−=>(%_(. p q) r)
285+=. p q
286+r
153287```
154288
155−##### Syntax
289+Wide form:
156290
157−Regular: **3-fixed**.
291+```hoon
292+=.(p q r)
293+```
158294
159−##### Discussion
295+Irregular form:
160296
161−Technically the `=.` rune doesn't change the subject. It creates
162−a new subject just like the old one except for a changed value at `p`. Note that the mutation uses [`%_` ("cencab")](/docs/hoon/reference/rune/cen#cencab), so the type at `p` doesn't change. Trying to change the value type results in a `nest-fail`.
297+None.
163298
164−##### Examples
299+#### AST
300+
301+```hoon
302+[%tsdt p=wing q=hoon r=hoon]
303+```
304+
305+#### Expands to
306+
307+```hoon
308+=>(%_(. p q) r)
309+```
310+
311+#### Discussion
312+
313+Technically the `=.` rune doesn't change the subject. It creates a new subject
314+just like the old one except for a changed value at `p`. Note that the mutation
315+uses [`%_` ("cencab")](/docs/hoon/reference/rune/cen#cencab), so the type at `p`
316+doesn't change. Trying to change the value type results in a `nest-fail`.
317+
318+#### Examples
165319
166320```
167321> =+ a=[b=1 c=2]
@@ -178,62 +332,117 @@ a new subject just like the old one except for a changed value at `p`. Note tha
178332nest-fail
179333```
180334
181−### `=-` "tishep"
335+---
182336
183−`[%tshp p=hoon q=hoon]`: combine a new noun with the subject, inverted.
337+## `=-` "tishep"
184338
185−##### Expands to
339+Combine a new noun with the subject, inverted.
340+
341+#### Syntax
342+
343+Two arguments, fixed.
344+
345+Tall form:
186346
187347```hoon
188−=>([q .] p)
348+=- p
349+q
350+```
351+
352+Wide form:
353+
354+```hoon
355+=-(p q)
189356```
190357
191−##### Syntax
358+Irregular form:
192359
193−Regular: **2-fixed**.
360+None.
194361
195−##### Discussion
362+#### AST
196363
197−`=-` 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.
364+```hoon
365+[%tshp p=hoon q=hoon]
366+```
367+
368+#### Expands to
369+
370+```hoon
371+=>([q .] p)
372+```
373+
374+#### Discussion
375+
376+`=-` is just like `=+` but its subexpressions are reversed. `=-` looks better
377+than `=+` when the expression you're pinning to the subject is much smaller than
378+the expression that uses it.
198379
199−##### Examples
380+#### Examples
200381
201382```
202−~zod:dojo> =foo |= a=@
203− =+ b=1
204− =- (add a b c)
205− c=2
206−~zod:dojo> (foo 5)
383+> =foo |= a=@
384+ =+ b=1
385+ =- (add a b c)
386+ c=2
387+> (foo 5)
2073888
208389```
209390
210−### `=^` "tisket"
391+---
211392
212−`[%tskt p=skin q=wing r=hoon s=hoon]`: pin the head of a pair; change
213−a leg with the tail.
393+## `=^` "tisket"
214394
215−##### Expands to
395+Pin the head of a pair; change a leg with the tail.
396+
397+#### Syntax
398+
399+Four arguments, fixed.
400+
401+Tall form:
216402
217403```hoon
218−=/(p -.r =.(q +.r s))
404+=^ p q
405+ r
406+s
219407```
220408
221−##### Syntax
409+Wide form:
222410
223−Regular: **4-fixed**.
411+```hoon
412+=^(p q r s)
413+```
224414
225−##### Discussion
415+Irregular form:
226416
227−`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.
417+None.
418+
419+#### AST
420+
421+```hoon
422+[%tskt p=skin q=wing r=hoon s=hoon]
423+```
424+
425+#### Expands to
426+
427+```hoon
428+=/(p -.r =.(q +.r s))
429+```
430+
431+#### Discussion
432+
433+`p` is a new name (possibly with type annotation, e.g., `a=@`) of a value to be
434+pinned to the subject. The value of `p` is the head of the product of `r`. `q`
435+is given the value of the tail of `r`'s product. Then `s` is evaluated against
436+this new subject.
228437
229438We generally use `=^` when we have a state machine with a function, `r`, that
230439produces a cell, whose head is a result and whose tail is a new
231−state. The head value is given a new name `p`, and the
440+state. The head value is given a new name `p`, and the
232441tail is stuffed back into wherever we stored the old state, `q`.
233442
234443This may also remind you of Haskell's State monad.
235444
236−##### Examples
445+#### Examples
237446
238447The `og` core is a stateful pseudo-random number generator.
239448We have to change the core state every time we generate a
@@ -247,114 +456,235 @@ random number, so we use `=^`:
247456[99 46]
248457```
249458
250−### `=<` "tisgal"
459+---
460+
461+## `=<` "tisgal"
251462
252−`[%tsgl p=hoon q=hoon]`: compose two expressions, inverted.
463+Compose two expressions, inverted.
253464
254−##### Expands to
465+#### Syntax
466+
467+Two arguments, fixed
468+
469+Tall form:
255470
256471```hoon
257−=>(q p)
472+=< p
473+q
258474```
259475
260−##### Syntax
476+Wide form:
261477
262−Regular: **2-fixed**.
478+```hoon
479+=<(p q)
480+```
263481
264−Irregular: `foo:baz` is `=<(foo baz)`.
482+Irregular form:
265483
266−##### Discussion
484+```hoon
485+p:q
486+```
487+
488+#### AST
489+
490+```hoon
491+[%tsgl p=hoon q=hoon]
492+```
493+
494+#### Expands to
495+
496+```hoon
497+=>(q p)
498+```
499+
500+#### Discussion
267501
268502`=<` is just `=>` backwards.
269503
270−##### Examples
504+#### Examples
271505
272506```
273−~zod:dojo> =<(b [a=1 b=2 c=3])
507+> =<(b [a=1 b=2 c=3])
2745082
275509
276−~zod:dojo> =< b
277− [a=1 b=2 c=3]
510+> =< b
511+ [a=1 b=2 c=3]
2785122
279513
280−~zod:dojo> b:[a=1 b=2 c=3]
514+> b:[a=1 b=2 c=3]
2815152
282516
283−~zod:dojo> [. .]:(add 2 4)
517+> [. .]:(add 2 4)
284518[6 6]
285519```
286520
287−### `=+` "tislus"
521+---
288522
523+## `=+` "tislus"
289524
290−`[%tsls p=hoon q=hoon]`: combine a new noun with the subject.
525+Combine a new noun with the subject.
291526
292−##### Expands to
527+#### Syntax
528+
529+Two arguments, fixed.
530+
531+Tall form:
293532
294533```hoon
295−=>([p .] q)
534+=+ p
535+q
296536```
297537
298−##### Syntax
538+Wide form:
299539
300−Regular: **2-fixed**.
540+```hoon
541+=+(p q)
542+```
543+
544+Irregular form:
545+
546+None.
547+
548+#### AST
549+
550+```hoon
551+[%tsls p=hoon q=hoon]
552+```
553+
554+#### Expands to
301555
302−##### Discussion
556+```hoon
557+=>([p .] q)
558+```
559+
560+#### Discussion
303561
304−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.
562+The subject of the `=+` expression, call it `a`, becomes the cell `[p a]` for
563+the evaluation of `q`. That is, `=+` 'pins a value', `p`, to the head of the
564+subject.
305565
306566Loosely speaking, `=+` is the simplest way of "declaring a variable."
307567
308−##### Examples
568+#### Examples
569+
570+```
571+> =+ 42 -
572+42
573+
574+> =+ x=42 x
575+42
576+
577+> =+ [a='foo' b='bar'] a
578+'foo'
579+```
580+
581+---
582+
583+## `=;` "tismic"
309584
310−### `=;` "tismic"
585+Combine a named noun with the subject, possibly with type annotation; inverted
586+order.
311587
312−`[%tsmc p=skin q=hoon r=hoon]`: combine a named noun with the subject, possibly with type annotation; inverted order.
588+#### Syntax
313589
314−##### Expands to
590+Three arguments, fixed.
591+
592+Tall form:
315593
316594```hoon
317−=/(p r q)
595+=; p
596+ q
597+r
318598```
319599
320−##### Syntax
600+Wide form:
321601
322−Regular: **3-fixed**.
602+```hoon
603+=;(p q r)
604+```
323605
324−##### Discussion
606+Irregular form:
325607
326−`=;` is exactly like `=/` except that the order of its last two subexpressions is reversed.
608+None.
327609
328−##### Examples
610+#### AST
329611
612+```hoon
613+[%tsmc p=skin q=hoon r=hoon]
330614```
331−~zod:dojo> =foo |= a=@
332− =/ b 1
333− =; c=@ :(add a b c)
334− 2
335−~zod:dojo> (foo 5)
615+
616+#### Expands to
617+
618+```hoon
619+=/(p r q)
620+```
621+
622+#### Discussion
623+
624+`=;` is exactly like `=/` except that the order of its last two subexpressions
625+is reversed.
626+
627+#### Examples
628+
629+```
630+> =foo |= a=@
631+ =/ b 1
632+ =; c=@
633+ :(add a b c)
634+ 2
635+> (foo 5)
3366368
337637```
338638
339−### `=/` "tisfas"
639+---
640+
641+## `=/` "tisfas"
642+
643+Combine a named noun with the subject, possibly with type annotation.
644+
645+#### Syntax
646+
647+Three arguments, fixed.
648+
649+Tall form:
650+
651+```hoon
652+=/ p
653+ q
654+r
655+```
656+
657+Wide form:
658+
659+```hoon
660+=/(p q r)
661+```
662+
663+Irregular form:
340664
341−`[%tsfs p=skin q=hoon r=hoon]`: combine a named noun with the subject, possibly with type annotation.
665+None.
342666
343−##### Expands to
667+#### AST
344668
345−**if `p` is a name**, (e.g. `a`):
669+```hoon
670+[%tsfs p=skin q=hoon r=hoon]
671+```
672+
673+#### Expands to
674+
675+if `p` is a name, (e.g. `a`):
346676
347677```hoon
348678=+(^=(p q) r)
349679```
350680
351−**if `p` is a name with a type** (e.g., `a=@`):
681+if `p` is a name with a type (e.g., `a=@`):
352682
353683```hoon
354684=+(^-(p q) r)
355685```
356686
357−##### Desugaring
687+#### Desugaring
358688
359689```hoon
360690?@ p
@@ -364,76 +694,139 @@ Regular: **3-fixed**.
364694r
365695```
366696
367−##### Syntax
697+#### Discussion
368698
369−Regular: **3-fixed**.
699+`p` can be either a name or a `name=type`. If it's just a name, `=/` ("tisfas")
700+"declares a type-inferred variable." If it has a type, `=/` "declares a
701+type-checked variable."
370702
371−##### Discussion
703+#### Examples
372704
373−`p` can be either a name or a name=type. If it's just a name,
374−`=/` ("tisfas") "declares a type-inferred variable." If it has a type, `=/`
375−"declares a type-checked variable."
705+```
706+> =/ a=@t 'hello' a
707+'hello'
376708
377−##### Examples
709+> =/ x [1 2 3] x
710+[1 2 3]
378711
379−```
380−~zod:dojo> =foo |= a=@
381− =/ b 1
382− =/ c=@ 2
383− :(add a b c)
384−~zod:dojo> (foo 5)
712+> =foo |= a=@
713+ =/ b 1
714+ =/ c=@ 2
715+ :(add a b c)
716+> (foo 5)
3857178
386718```
387719
388−### `=~` "tissig"
720+---
389721
722+## `=~` "tissig"
390723
391−`[%tssg p=(list hoon)]`: compose many expressions.
724+Compose many expressions.
392725
393−##### Produces
726+#### Syntax
394727
395−The product of the chain composition.
728+Variable number of arguments.
396729
397−##### Syntax
730+Tall form:
398731
399−Regular: **running**.
732+```hoon
733+=~ p1
734+ p2
735+ p3
736+ pn
737+==
738+```
400739
401−##### Examples
740+Wide form:
402741
742+```hoon
743+=~(p1 p2 p3 pn)
744+```
745+
746+Irregular form:
747+
748+None.
749+
750+#### AST
751+
752+```hoon
753+[%tssg p=(list hoon)]
403754```
404−~zod:dojo> =~ [sub (mul 3 20) (add 10 20)]
755+
756+#### Produces
757+
758+The product of the chain composition.
759+
760+#### Examples
761+
762+```
763+> =~ 10
764+ [20 .]
765+ [30 .]
766+ [40 .]
767+ .
768+ ==
769+[40 30 20 10]
770+
771+> =~ [sub (mul 3 20) (add 10 20)]
405772 (sub +)
406773 +(.)
407774 ==
40877531
409776
410−~zod:dojo> =foo =| n=@
411− =< =~ increment
412− increment
413− increment
414− n
415− ==
416− |%
417− ++ increment
418− ..increment(n +(n))
419− --
420−~zod:dojo> foo
777+> =foo =| n=@
778+ =< =~ increment
779+ increment
780+ increment
781+ n
782+ ==
783+ |%
784+ ++ increment
785+ ..increment(n +(n))
786+ --
787+> foo
4217883
422789```
423790
424−### `=*` "tistar" {#tistar}
791+---
425792
426−`[%tstr p=term q=hoon r=hoon]`: define a deferred expression.
793+## `=*` "tistar" {#tistar}
427794
428−##### Produces
795+Define a deferred expression.
429796
430−`r`, compiled with a subject in which `p` is a deferred expression for `q`.
797+#### Syntax
798+
799+Three arguments, fixed.
800+
801+Tall form:
802+
803+```hoon
804+=* p
805+ q
806+r
807+```
808+
809+Wide form:
810+
811+```hoon
812+=*(p q r)
813+```
814+
815+Irregular form:
431816
432−##### Syntax
817+None.
433818
434−Regular: **3-fixed**.
819+#### AST
820+
821+```hoon
822+[%tstr p=term q=hoon r=hoon]
823+```
824+
825+#### Produces
826+
827+`r`, compiled with a subject in which `p` is a deferred expression for `q`.
435828
436−##### Discussion
829+#### Discussion
437830
438831`=*` assigns a name to an expression that will be evaluated in each place the
439832name is dereferenced. This allows you to "write" through it to the original
@@ -443,47 +836,81 @@ calculated every time you use `p`.
443836This rune has some similarities with macros, and some similarities with aliases,
444837but it is not really either.
445838
446−##### Examples
839+This rune is commonly used to give a Gall agent's state the name `state` like:
840+
841+```hoon
842+=* state -
843+```
844+
845+This lets you reference the whole `state` while also being able to reference its
846+individual elements like `foo` and `bar`, without having to do `foo.state`,
847+`bar.state`, etc.
848+
849+#### Examples
447850
448851```
449−~zod:dojo>
450− =+ a=1
451− =* b a
452− [a b]
852+> =+ a=1
853+ =* b a
854+ [a b]
453855[1 1]
454856
455−~zod:dojo>
456− =+ a=1
457− =* b a
458− =. a 2
459− [a b]
857+> =+ a=1
858+ =* b a
859+ =. a 2
860+ [a b]
460861[2 2]
461862```
462863
463−### `=?` "tiswut"
864+---
865+
866+## `=?` "tiswut"
867+
868+Conditionally change one leg in the subject.
869+
870+#### Syntax
464871
465−`[$tswt p=wing q=hoon r=hoon s=hoon]`: conditionally change one leg in the subject.
872+Four arguments, fixed.
466873
467−##### Expands to
874+Tall form:
468875
469876```hoon
470−=. p ?:(q r p)
877+=? p q
878+ r
471879s
472880```
473881
474−##### Syntax
882+Wide form:
883+
884+```hoon
885+=?(p q r s)
886+```
887+
888+Irregular form:
889+
890+None.
891+
892+#### AST
893+
894+```hoon
895+[%tswt p=wing q=hoon r=hoon s=hoon]
896+```
897+
898+#### Expands to
475899
476−Regular: **4-fixed**.
900+```hoon
901+=. p ?:(q r p)
902+s
903+```
477904
478−##### Discussion
905+#### Discussion
479906
480907Use `=?` to replace the value of leg `p` with `r` on condition `q`. As
481908usual, we are not actually mutating the subject, just creating
482−a new subject with a changed value. The change in value includes a
909+a new subject with a changed value. The change in value includes a
483910type check against the old subject; the type of `r` must nest under
484911the type of `p`.
485912
486−##### Examples
913+#### Examples
487914
488915```
489916> =a 12