git.iko.soy/urbit.org
on master help sign in
update dot, zap tis
1948a55Tinnus Napbus
content/docs/hoon/reference/rune/dot.md+74−70
compare with master
unifiedsplit
@@ -11,17 +11,7 @@ Anything Nock can do, Hoon can do also. These runes are used for carrying out No
11
11
12Load from the Arvo namespace (scry) with a fake Nock instruction: Nock 12.
12Load from the Arvo namespace (scry) with a fake Nock instruction: Nock 12.
13
13
14−#### AST
14+#### Syntax
15−
16−```hoon
17−[%dtkt p=spec q=hoon]
18−```
19−
20−#### Produces
21−
22−The noun `q`, cast to the type `p`.
23−
24−#### Regular syntax
25
15
26Two arguments, with the second optionally split into an arbitrary number of
16Two arguments, with the second optionally split into an arbitrary number of
27elements.
17elements.
@@ -32,27 +22,37 @@ with a `==`. Note also that the `==` does not make the arguments into a list as
32you might expect, so `q` must be explicitly null-terminated if its elements are
22you might expect, so `q` must be explicitly null-terminated if its elements are
33specified separately.
23specified separately.
34
24
35−Tall-form:
25+Tall form:
36
26
37```hoon
27```hoon
38.^ p
28.^ p
39− q-1
29+ q1
40− q-2
30+ q2
41− q-3
31+ q3
42− q-n
32+ qn
43==
33==
44```
34```
45
35
46−Wide-form:
36+Wide form:
47
37
48```hoon
38```hoon
49−.^(p q-1 q-2)
39+.^(p q1 q2)
50```
40```
51
41
52−#### Irregular syntax
42+Irregular form:
53
43
54None.
44None.
55
45
46+#### AST
47+
48+```hoon
49+[%dtkt p=spec q=hoon]
50+```
51+
52+#### Produces
53+
54+The noun `q`, cast to the type `p`.
55+
56#### Discussion
56#### Discussion
57
57
58Nock has no `12` instruction! But the virtual Nock
58Nock has no `12` instruction! But the virtual Nock
@@ -120,38 +120,38 @@ You can modify the time of the file listing quite simply and ask for a listing f
120
120
121Increment an atom with Nock `4`.
121Increment an atom with Nock `4`.
122
122
123−#### AST
123+#### Syntax
124−
125−```hoon
126−[%dtls p=hoon]
127−```
128−
129−#### Produces
130−
131−`p` plus `1` if `p` is an atom; otherwise, crashes. The product atom has no aura.
132−
133−#### Regular syntax
134
124
135One argument, fixed.
125One argument, fixed.
136
126
137−Tall-form:
127+Tall form:
138
128
139```hoon
129```hoon
140.+ p
130.+ p
141```
131```
142
132
143−Wide-form:
133+Wide form:
144
134
145```hoon
135```hoon
146.+(p)
136.+(p)
147```
137```
148
138
149−#### Irregular syntax
139+Irregular form:
150
140
151```hoon
141```hoon
152+(p)
142+(p)
153```
143```
154
144
145+#### AST
146+
147+```hoon
148+[%dtls p=hoon]
149+```
150+
151+#### Produces
152+
153+`p` plus `1` if `p` is an atom; otherwise, crashes. The product atom has no aura.
154+
155#### Examples
155#### Examples
156
156
157```
157```
@@ -174,33 +174,37 @@ nest-fail
174
174
175Evaluate with Nock `2`.
175Evaluate with Nock `2`.
176
176
177−#### AST
178−
179−```hoon
180−[%dttr p=hoon q=hoon]
181−```
182−
183#### Produces
177#### Produces
184
178
185Nock of formula `q` and subject `p`, with type `%noun`.
179Nock of formula `q` and subject `p`, with type `%noun`.
186
180
187−#### Regular syntax
181+#### Syntax
188
182
189Two arguments, fixed.
183Two arguments, fixed.
190
184
191−Tall-form:
185+Tall form:
192
186
193```hoon
187```hoon
194.* p
188.* p
195q
189q
196```
190```
197
191
198−Wide-form:
192+Wide form:
199
193
200```hoon
194```hoon
201.*(p q)
195.*(p q)
202```
196```
203
197
198+Irregular form:
199+
200+None.
201+
202+#### AST
203+
204+```hoon
205+[%dttr p=hoon q=hoon]
206+```
207+
204#### Discussion
208#### Discussion
205
209
206`.*(p q)` is used to run Nock formula `q` on the subject `p` from within Hoon.
210`.*(p q)` is used to run Nock formula `q` on the subject `p` from within Hoon.
@@ -238,39 +242,39 @@ therefore possible to use Hoon as a typeless language.
238
242
239Test for equality with Nock `5`.
243Test for equality with Nock `5`.
240
244
241−#### AST
245+#### Syntax
242−
243−```hoon
244−[%dtts p=hoon q=hoon]
245−```
246−
247−#### Produces
248−
249−`%.y` if `p` equals `q`; otherwise `%.n`.
250−
251−#### Regular syntax
252
246
253Two arguments, fixed.
247Two arguments, fixed.
254
248
255−Tall-form:
249+Tall form:
256
250
257```hoon
251```hoon
258.= p
252.= p
259q
253q
260```
254```
261
255
262−Wide-form:
256+Wide form:
263
257
264```hoon
258```hoon
265.=(p q)
259.=(p q)
266```
260```
267
261
268−#### Irregular syntax
262+Irregular form:
269
263
270```hoon
264```hoon
271=(p q)
265=(p q)
272```
266```
273
267
268+#### AST
269+
270+```hoon
271+[%dtts p=hoon q=hoon]
272+```
273+
274+#### Produces
275+
276+`%.y` if `p` equals `q`; otherwise `%.n`.
277+
274#### Discussion
278#### Discussion
275
279
276Like Nock equality, `.=` ("dottis") tests whether two nouns are the same,
280Like Nock equality, `.=` ("dottis") tests whether two nouns are the same,
@@ -304,36 +308,36 @@ nouns. (Comparing large duplicates is a common cause of performance bugs.)
304
308
305Test for cell or atom with Nock `3`.
309Test for cell or atom with Nock `3`.
306
310
307−#### AST
311+#### Syntax
308−
309−```hoon
310−[%dtwt p=hoon]
311−```
312−
313−#### Produces
314−
315−`%.y` if `p` is a cell; otherwise `%.n`.
316−
317−#### Regular syntax
318
312
319One argument, fixed.
313One argument, fixed.
320
314
321−Tall-form:
315+Tall form:
322
316
323```hoon
317```hoon
324.? p
318.? p
325```
319```
326
320
327−Wide-form:
321+Wide form:
328
322
329```hoon
323```hoon
330.?(p)
324.?(p)
331```
325```
332
326
333−#### Irregular syntax
327+Irregular form:
334
328
335None.
329None.
336
330
331+#### AST
332+
333+```hoon
334+[%dtwt p=hoon]
335+```
336+
337+#### Produces
338+
339+`%.y` if `p` is a cell; otherwise `%.n`.
340+
337#### Examples
341#### Examples
338
342
339```
343```
content/docs/hoon/reference/rune/tis.md+613−186
@@ -4,127 +4,254 @@ weight = 5
4template = "doc.html"
4template = "doc.html"
5+++
5+++
6
6
7−These runes modify the subject. (Or more precisely, they
7+These runes modify the subject. (Or more precisely, they
8evaluate at least one of their subexpressions with a modified subject.)
8evaluate at least one of their subexpressions with a modified subject.)
9
9
10## Overview
10## Overview
11
11
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
13to a value, e.g., `a` to `12`, you do so by pinning `12` to the subject and
13to 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 `=`
15family of runes.
15family of runes.
16
16
17−Let's say you have some old subject `p`. To 'pin' a value to the head means to
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
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
19+the cell is the new value. So to pin `12` with the face `a` the new subject
20would be: `[a=12 p]`.
20would be: `[a=12 p]`.
21
21
22Of course there are many variations on ways to modify the subject, useful for
22Of 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.
24
24
25−## Runes
25+---
26
26
27−### `=>` "tisgar"
27+## `=>` "tisgar"
28
28
29−`[%tsgr p=hoon q=hoon]`: compose two expressions.
29+Compose two expressions.
30
30
31−##### Produces
31+#### Syntax
32
32
33−the product of `q`, with the product of `p` taken as the subject.
33+Two arguments, fixed.
34
34
35−##### Syntax
35+Tall form:
36
36
37−Regular: **2-fixed**.
37+```hoon
38+=> p
39+q
40+```
38
41
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+
39−##### Examples
62+#### Examples
40
63
41```
64```
42> =>([a=1 b=2 c=3] b)
65> =>([a=1 b=2 c=3] b)
432
662
44
67
68+> => 9 .
69+9
70+
45> =>((add 2 4) [. .])
71> =>((add 2 4) [. .])
46[6 6]
72[6 6]
73+
74+> =>
75+ |%
76+ ++ foo
77+ |= [a=@ b=@]
78+ [b a]
79+ --
80+ (foo 42 27)
81+[27 42]
47```
82```
48
83
84+---
85+
49−### `=|` "tisbar"
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+```
50
100
101+Wide form:
51
102
103+```hoon
104+=|(p q)
105+```
106+
107+Irregular form:
108+
109+None.
110+
111+#### AST
112+
113+```hoon
52−`[%tsbr p=spec q=hoon]`: combine a default type value with the subject.
114+[%tsbr p=spec q=hoon]
115+```
53
116
54−##### Expands to
117+#### Expands to
55
118
56```hoon
119```hoon
57=+(*p q)
120=+(*p q)
58```
121```
59
122
60−##### Syntax
123+#### Discussion
61
124
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.
63
127
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.
65
130
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
67
132
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"
69
144
70−##### Examples
145+Change multiple legs in the subject.
71
146
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
72```
159```
73−~zod:dojo> =foo |= a=@
160+
74− =| b=@
161+Wide form:
75− =- :(add a b c)
162+
76− c=2
163+```hoon
77−~zod:dojo> (foo 5)
164+=:(p1a p1b, p2a p2b, p3a p3b q)
78−7
79```
165```
80
166
81−### `=:` "tiscol"
167+Irregular form:
82
168
83−`[%tscl p=(list (pair wing hoon)) q=hoon]`: change multiple legs in the subject.
169+None.
84
170
85−##### Expands to
171+#### AST
86
172
87```hoon
173```hoon
88−=>(%_(. p) q)
174+[%tscl p=(list (pair wing hoon)) q=hoon]
89```
175```
90
176
91−##### Syntax
177+#### Expands to
92
178
93−Regular: **jogging**, then **1-fixed**.
179+```hoon
180+=>(%_(. p) q)
181+```
94
182
95−##### Discussion
183+#### Discussion
96
184
97This rune is like `=.`, but for modifying the values of multiple legs of the subject.
185This rune is like `=.`, but for modifying the values of multiple legs of the subject.
98
186
99−##### Examples
187+#### Examples
100
188
101```
189```
102−~zod:dojo> =+ a=[b=1 c=2]
190+> =+ a=[b=1 c=2]
103− =: c.a 4
191+ =: c.a 4
104− b.a 3
192+ b.a 3
105− ==
193+ ==
106− a
194+ a
107[b=3 c=4]
195[b=3 c=4]
108```
196```
109
197
198+---
199+
110−### `=,` "tiscom"
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+```
111
220
112−`[%tscm p=hoon q=hoon]`: expose namespace
221+Irregular form:
113
222
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.
115
224
116−##### Syntax
225+#### AST
117
226
118−Regular: **2-fixed**.
227+```hoon
228+[%tscm p=hoon q=hoon]
229+```
119
230
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+
120−##### Examples
247+#### Examples
121
248
122With an imported core:
249With an imported core:
123
250
124```
251```
125> (sum -7 --7)
252> (sum -7 --7)
126-find.sum
253-find.sum
127−[crash message]
254+dojo: hoon expression failed
128
255
129> (sum:si -7 --7)
256> (sum:si -7 --7)
130--0
257--0
@@ -142,26 +269,53 @@ With a dojo-defined face:
142[2 4]
269[2 4]
143```
270```
144
271
272+---
273+
145−### `=.` "tisdot"
274+## `=.` "tisdot"
275+
276+Change one leg in the subject.
146
277
147−`[%tsdt p=wing q=hoon r=hoon]`: change one leg in the subject.
278+#### Syntax
148
279
149−##### Expands to
280+Three arguments, fixed.
281+
282+Tall form:
150
283
151```hoon
284```hoon
152−=>(%_(. p q) r)
285+=. p q
286+r
153```
287```
154
288
155−##### Syntax
289+Wide form:
156
290
157−Regular: **3-fixed**.
291+```hoon
292+=.(p q r)
293+```
158
294
159−##### Discussion
295+Irregular form:
160
296
161−Technically the `=.` rune doesn't change the subject. It creates
297+None.
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`.
163
298
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+
164−##### Examples
318+#### Examples
165
319
166```
320```
167> =+ a=[b=1 c=2]
321> =+ 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
178nest-fail
332nest-fail
179```
333```
180
334
181−### `=-` "tishep"
335+---
182
336
183−`[%tshp p=hoon q=hoon]`: combine a new noun with the subject, inverted.
337+## `=-` "tishep"
184
338
185−##### Expands to
339+Combine a new noun with the subject, inverted.
340+
341+#### Syntax
342+
343+Two arguments, fixed.
344+
345+Tall form:
186
346
187```hoon
347```hoon
348+=- p
349+q
350+```
351+
352+Wide form:
353+
354+```hoon
188−=>([q .] p)
355+=-(p q)
189```
356```
190
357
191−##### Syntax
358+Irregular form:
192
359
193−Regular: **2-fixed**.
360+None.
194
361
195−##### Discussion
362+#### AST
196
363
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
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.
377+than `=+` when the expression you're pinning to the subject is much smaller than
378+the expression that uses it.
198
379
199−##### Examples
380+#### Examples
200
381
201```
382```
202−~zod:dojo> =foo |= a=@
383+> =foo |= a=@
203− =+ b=1
384+ =+ b=1
204− =- (add a b c)
385+ =- (add a b c)
205− c=2
386+ c=2
206−~zod:dojo> (foo 5)
387+> (foo 5)
2078
3888
208```
389```
209
390
210−### `=^` "tisket"
391+---
211
392
212−`[%tskt p=skin q=wing r=hoon s=hoon]`: pin the head of a pair; change
393+## `=^` "tisket"
213−a leg with the tail.
214
394
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:
216
402
217```hoon
403```hoon
218−=/(p -.r =.(q +.r s))
404+=^ p q
405+ r
406+s
219```
407```
220
408
221−##### Syntax
409+Wide form:
222
410
223−Regular: **4-fixed**.
411+```hoon
412+=^(p q r s)
413+```
224
414
225−##### Discussion
415+Irregular form:
226
416
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`
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.
435+is given the value of the tail of `r`'s product. Then `s` is evaluated against
436+this new subject.
228
437
229We generally use `=^` when we have a state machine with a function, `r`, that
438We generally use `=^` when we have a state machine with a function, `r`, that
230produces a cell, whose head is a result and whose tail is a new
439produces 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
232tail is stuffed back into wherever we stored the old state, `q`.
441tail is stuffed back into wherever we stored the old state, `q`.
233
442
234This may also remind you of Haskell's State monad.
443This may also remind you of Haskell's State monad.
235
444
236−##### Examples
445+#### Examples
237
446
238The `og` core is a stateful pseudo-random number generator.
447The `og` core is a stateful pseudo-random number generator.
239We have to change the core state every time we generate a
448We have to change the core state every time we generate a
@@ -247,114 +456,235 @@ random number, so we use `=^`:
247[99 46]
456[99 46]
248```
457```
249
458
459+---
460+
250−### `=<` "tisgal"
461+## `=<` "tisgal"
251
462
252−`[%tsgl p=hoon q=hoon]`: compose two expressions, inverted.
463+Compose two expressions, inverted.
253
464
254−##### Expands to
465+#### Syntax
466+
467+Two arguments, fixed
468+
469+Tall form:
255
470
256```hoon
471```hoon
257−=>(q p)
472+=< p
473+q
258```
474```
259
475
260−##### Syntax
476+Wide form:
261
477
262−Regular: **2-fixed**.
478+```hoon
479+=<(p q)
480+```
263
481
264−Irregular: `foo:baz` is `=<(foo baz)`.
482+Irregular form:
265
483
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+
266−##### Discussion
500+#### Discussion
267
501
268`=<` is just `=>` backwards.
502`=<` is just `=>` backwards.
269
503
270−##### Examples
504+#### Examples
271
505
272```
506```
273−~zod:dojo> =<(b [a=1 b=2 c=3])
507+> =<(b [a=1 b=2 c=3])
2742
5082
275
509
276−~zod:dojo> =< b
510+> =< b
277− [a=1 b=2 c=3]
511+ [a=1 b=2 c=3]
2782
5122
279
513
280−~zod:dojo> b:[a=1 b=2 c=3]
514+> b:[a=1 b=2 c=3]
2812
5152
282
516
283−~zod:dojo> [. .]:(add 2 4)
517+> [. .]:(add 2 4)
284[6 6]
518[6 6]
285```
519```
286
520
287−### `=+` "tislus"
521+---
288
522
523+## `=+` "tislus"
289
524
290−`[%tsls p=hoon q=hoon]`: combine a new noun with the subject.
525+Combine a new noun with the subject.
291
526
292−##### Expands to
527+#### Syntax
528+
529+Two arguments, fixed.
530+
531+Tall form:
293
532
294```hoon
533```hoon
295−=>([p .] q)
534+=+ p
535+q
296```
536```
297
537
298−##### Syntax
538+Wide form:
299
539
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
301
555
556+```hoon
557+=>([p .] q)
558+```
559+
302−##### Discussion
560+#### Discussion
303
561
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.
305
565
306Loosely speaking, `=+` is the simplest way of "declaring a variable."
566Loosely speaking, `=+` is the simplest way of "declaring a variable."
307
567
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"
309
584
310−### `=;` "tismic"
585+Combine a named noun with the subject, possibly with type annotation; inverted
586+order.
311
587
312−`[%tsmc p=skin q=hoon r=hoon]`: combine a named noun with the subject, possibly with type annotation; inverted order.
588+#### Syntax
313
589
314−##### Expands to
590+Three arguments, fixed.
591+
592+Tall form:
315
593
316```hoon
594```hoon
317−=/(p r q)
595+=; p
596+ q
597+r
318```
598```
319
599
320−##### Syntax
600+Wide form:
321
601
322−Regular: **3-fixed**.
602+```hoon
603+=;(p q r)
604+```
323
605
324−##### Discussion
606+Irregular form:
325
607
326−`=;` is exactly like `=/` except that the order of its last two subexpressions is reversed.
608+None.
327
609
328−##### Examples
610+#### AST
329
611
612+```hoon
613+[%tsmc p=skin q=hoon r=hoon]
330```
614```
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+```
331−~zod:dojo> =foo |= a=@
630+> =foo |= a=@
332− =/ b 1
631+ =/ b 1
632+ =; c=@
333− =; c=@ :(add a b c)
633+ :(add a b c)
334− 2
634+ 2
335−~zod:dojo> (foo 5)
635+> (foo 5)
3368
6368
337```
637```
338
638
639+---
640+
339−### `=/` "tisfas"
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:
340
664
341−`[%tsfs p=skin q=hoon r=hoon]`: combine a named noun with the subject, possibly with type annotation.
665+None.
342
666
343−##### Expands to
667+#### AST
344
668
669+```hoon
670+[%tsfs p=skin q=hoon r=hoon]
671+```
672+
673+#### Expands to
674+
345−**if `p` is a name**, (e.g. `a`):
675+if `p` is a name, (e.g. `a`):
346
676
347```hoon
677```hoon
348=+(^=(p q) r)
678=+(^=(p q) r)
349```
679```
350
680
351−**if `p` is a name with a type** (e.g., `a=@`):
681+if `p` is a name with a type (e.g., `a=@`):
352
682
353```hoon
683```hoon
354=+(^-(p q) r)
684=+(^-(p q) r)
355```
685```
356
686
357−##### Desugaring
687+#### Desugaring
358
688
359```hoon
689```hoon
360?@ p
690?@ p
@@ -364,76 +694,139 @@ Regular: **3-fixed**.
364r
694r
365```
695```
366
696
367−##### Syntax
697+#### Discussion
368
698
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."
370
702
371−##### Discussion
703+#### Examples
372
704
373−`p` can be either a name or a name=type. If it's just a name,
705+```
374−`=/` ("tisfas") "declares a type-inferred variable." If it has a type, `=/`
706+> =/ a=@t 'hello' a
375−"declares a type-checked variable."
707+'hello'
376
708
377−##### Examples
709+> =/ x [1 2 3] x
710+[1 2 3]
378
711
379−```
380−~zod:dojo> =foo |= a=@
712+> =foo |= a=@
381− =/ b 1
713+ =/ b 1
382− =/ c=@ 2
714+ =/ c=@ 2
383− :(add a b c)
715+ :(add a b c)
384−~zod:dojo> (foo 5)
716+> (foo 5)
3858
7178
386```
718```
387
719
388−### `=~` "tissig"
720+---
389
721
722+## `=~` "tissig"
390
723
391−`[%tssg p=(list hoon)]`: compose many expressions.
724+Compose many expressions.
392
725
393−##### Produces
726+#### Syntax
394
727
395−The product of the chain composition.
728+Variable number of arguments.
396
729
397−##### Syntax
730+Tall form:
398
731
399−Regular: **running**.
732+```hoon
733+=~ p1
734+ p2
735+ p3
736+ pn
737+==
738+```
400
739
401−##### Examples
740+Wide form:
402
741
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)]
403```
754```
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+
404−~zod:dojo> =~ [sub (mul 3 20) (add 10 20)]
771+> =~ [sub (mul 3 20) (add 10 20)]
405 (sub +)
772 (sub +)
406 +(.)
773 +(.)
407 ==
774 ==
40831
77531
409
776
410−~zod:dojo> =foo =| n=@
777+> =foo =| n=@
411− =< =~ increment
778+ =< =~ increment
412− increment
779+ increment
413− increment
780+ increment
414− n
781+ n
415− ==
782+ ==
416− |%
783+ |%
417− ++ increment
784+ ++ increment
418− ..increment(n +(n))
785+ ..increment(n +(n))
419− --
786+ --
420−~zod:dojo> foo
787+> foo
4213
7883
422```
789```
423
790
424−### `=*` "tistar" {#tistar}
791+---
425
792
426−`[%tstr p=term q=hoon r=hoon]`: define a deferred expression.
793+## `=*` "tistar" {#tistar}
427
794
428−##### Produces
795+Define a deferred expression.
429
796
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:
431
816
432−##### Syntax
817+None.
433
818
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`.
435
828
436−##### Discussion
829+#### Discussion
437
830
438`=*` assigns a name to an expression that will be evaluated in each place the
831`=*` assigns a name to an expression that will be evaluated in each place the
439name is dereferenced. This allows you to "write" through it to the original
832name is dereferenced. This allows you to "write" through it to the original
@@ -443,47 +836,81 @@ calculated every time you use `p`.
443This rune has some similarities with macros, and some similarities with aliases,
836This rune has some similarities with macros, and some similarities with aliases,
444but it is not really either.
837but it is not really either.
445
838
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+
446−##### Examples
849+#### Examples
447
850
448```
851```
449−~zod:dojo>
450− =+ a=1
852+> =+ a=1
451− =* b a
853+ =* b a
452− [a b]
854+ [a b]
453[1 1]
855[1 1]
454
856
455−~zod:dojo>
456− =+ a=1
857+> =+ a=1
457− =* b a
858+ =* b a
458− =. a 2
859+ =. a 2
459− [a b]
860+ [a b]
460[2 2]
861[2 2]
461```
862```
462
863
864+---
865+
463−### `=?` "tiswut"
866+## `=?` "tiswut"
867+
868+Conditionally change one leg in the subject.
869+
870+#### Syntax
464
871
465−`[$tswt p=wing q=hoon r=hoon s=hoon]`: conditionally change one leg in the subject.
872+Four arguments, fixed.
466
873
467−##### Expands to
874+Tall form:
468
875
469```hoon
876```hoon
470−=. p ?:(q r p)
877+=? p q
878+ r
471s
879s
472```
880```
473
881
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
475
899
476−Regular: **4-fixed**.
900+```hoon
901+=. p ?:(q r p)
902+s
903+```
477
904
478−##### Discussion
905+#### Discussion
479
906
480Use `=?` to replace the value of leg `p` with `r` on condition `q`. As
907Use `=?` to replace the value of leg `p` with `r` on condition `q`. As
481usual, we are not actually mutating the subject, just creating
908usual, 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
483type check against the old subject; the type of `r` must nest under
910type check against the old subject; the type of `r` must nest under
484the type of `p`.
911the type of `p`.
485
912
486−##### Examples
913+#### Examples
487
914
488```
915```
489> =a 12
916> =a 12
content/docs/hoon/reference/rune/zap.md+314−115
@@ -5,167 +5,158 @@ template = "doc.html"
5aliases = ["docs/reference/hoon-expressions/rune/zap/"]
5aliases = ["docs/reference/hoon-expressions/rune/zap/"]
6+++
6+++
7
7
8−## Runes
8+## `!>` "zapgar"
9
9
10−### `!>` "zapgar"
10+Wrap a noun in its type (form a [`vase`](/docs/hoon/reference/stdlib/4o#vase)).
11
11
12−`[%zpgr p=hoon]`: wrap a noun in its type.
12+#### Syntax
13
13
14−##### Produces
14+One argument, fixed.
15
15
16−A cell whose tail is the product of `p`, and whose head is the static type of `p`.
16+Tall form:
17+
18+```hoon
19+!> p
20+```
21+
22+Wide form:
23+
24+```hoon
25+!>(p)
26+```
27+
28+Irregular form:
29+
30+None.
31+
32+#### AST
17
33
18−##### Syntax
34+```hoon
35+[%zpgr p=hoon]
36+```
37+
38+#### Produces
19
39
20−Regular: **1-fixed**.
40+A cell whose tail is the product of `p`, and whose head is the static type of `p`.
21
41
22−##### Discussion
42+#### Discussion
23
43
24−In Hoon, a dynamic type is a static type compiled at runtime. This type-noun cell is generally called a `vase`.
44+In Hoon, a dynamic type is a static type compiled at runtime. This type-noun
45+cell is generally called a [`vase`](/docs/hoon/reference/stdlib/4o#vase).
25
46
26−##### Examples
47+#### Examples
27
48
28```
49```
29> !>(1)
50> !>(1)
30[#t/@ud q=1]
51[#t/@ud q=1]
31```
52```
32
53
33−If you want just the type value, use a 'type spear'. This is `-:!>`, i.e., the head of the cell produced by `!>`:
54+If you want just the type value, use a 'type spear'. This is `-:!>`, i.e., the
55+head of the cell produced by `!>`:
34
56
35```
57```
36> -:!>(1)
58> -:!>(1)
37#t/@ud
59#t/@ud
38```
60```
39
61
40−### `!<` "zapgal"
62+---
41−
42−`[%zpld p=spec q=hoon]`
43
63
44−Takes a mold and a `vase` and dynamically checks that the type in the `vase`
64+## `!<` "zapgal"
45−matches the mold.
46
65
47−##### Produces
66+Extracts a [`vase`](/docs/hoon/reference/stdlib/4o#vase) to the given mold if
67+its type nests.
48
68
49−The value of `vase` typed with the type of the mold if possible, else a
69+#### Syntax
50−`nest-fail`.
51
70
52−##### Syntax
71+Two arguments, fixed.
53
72
54−Regular: **2-fixed**
73+Tall form:
55−
56−##### Discussion
57−
58−This is something like a partial inverse to the `!>` rune and can be used to extract
59−a typed value from a `vase`.
60−
61−##### Examples
62
74
75+```hoon
76+!< p
77+q
63```
78```
64−> !< @ !> ~zod
65−0
66
79
67−> !< @p !> 0
80+Wide form:
68−nest-fail
69
81
70−> =m !> 0
82+```hoon
71−> =n !> 1
83+!<(p q)
72−> !< [@ @] (slop m n)
73−[0 1]
74```
84```
75
85
76−### `!:` "zapcol"
86+Irregular form:
77−
78−`[%dbug p=hoon]`: turn on stack trace
79
87
80−##### Produces
88+None.
81
89
82−The product of `p` unless `p` crashes, in which case a stack trace is given.
90+#### AST
83−
84−##### Syntax
85−
86−Regular: **1-fixed**.
87
91
88```hoon
92```hoon
89−!: p=hoon
93+[%zpgl p=spec q=hoon]
90```
94```
91
95
96+#### Produces
97+
98+The value of vase `q` typed with the type of mold `p` if possible, else a
99+`nest-fail`.
100+
92−##### Discussion
101+#### Discussion
93
102
94−`!:` is used to turn on a debugging stack trace option for any code you have in `p`.
103+This is something like a partial inverse to the `!>` rune and can be used to
104+extract a typed value from a `vase`.
95
105
96−##### Examples
106+#### Examples
97
107
98```
108```
99−> ?:(=(0 1) 123 !!)
109+> !< @ !> ~zod
100−ford: %ride failed to execute:
110+0
101
111
102−> !: ?:(=(0 1) 123 !!)
112+> !< @p !> 0
103−/~zod/base/~2018.10.15..19.50.06..74af:<[1 5].[1 22]>
113+nest-fail
104−/~zod/base/~2018.10.15..19.50.06..74af:<[1 19].[1 21]>
114+
105−ford: %ride failed to execute:
115+> !< tape !>("foobar")
116+"foobar"
106```
117```
107
118
108−### `!.` "zapdot"
119+---
109
120
110−Turn off stack trace for a subexpression `p`
121+## `!=` "zaptis"
111
122
112−##### Produces
123+Make the Nock formula for a Hoon expression.
113
124
114−The product of `p`. If `p` crashes, no stack trace entries are given for that code.
125+#### Syntax
115
126
116−##### Syntax
127+One argument, fixed.
117
128
118−Regular: **1-fixed**.
129+Tall form:
119
130
120```hoon
131```hoon
121−!. p=hoon
132+!= p
122```
133```
123
134
124−`p` is any Hoon expression.
135+Wide form:
125−
126−##### Discussion
127−
128−`!.` is used to turn off a debugging stack trace option for any code you have in `p`. This rune can be embedded under a `!:` rune for inner loops of your code that you don't want or need to trace. This is especially useful if a trace overflows the stack.
129−
130−##### Examples
131
136
137+```hoon
138+!=(p)
132```
139```
133−> %.(1 |=(a=@ ^-(@ ?:(=(a 10) !! $(a +(a))))))
134−ford: %ride failed to execute:
135
140
136−> !: %.(1 |=(a=@ ^-(@ ?:(=(a 10) !! $(a +(a))))))
141+Irregular form:
137−/~zod/base/~2018.10.15..20.01.21..6b0c:<[1 5].[1 49]>
138−/~zod/base/~2018.10.15..20.01.21..6b0c:<[1 17].[1 47]>
139−/~zod/base/~2018.10.15..20.01.21..6b0c:<[1 22].[1 46]>
140−/~zod/base/~2018.10.15..20.01.21..6b0c:<[1 36].[1 45]>
141−...skipping some lines...
142−/~zod/base/~2018.10.15..20.01.21..6b0c:<[1 17].[1 47]>
143−/~zod/base/~2018.10.15..20.01.21..6b0c:<[1 22].[1 46]>
144−/~zod/base/~2018.10.15..20.01.21..6b0c:<[1 33].[1 35]>
145−ford: %ride failed to execute:
146
142
147−> !: %.(1 !.(|=(a=@ ^-(@ ?:(=(a 10) !! $(a +(a)))))))
143+None.
148−/~zod/base/~2018.10.15..20.01.35..0529:<[1 5].[1 53]>
149−ford: %ride failed to execute:
150−```
151
144
152−### `!=` "zaptis"
145+#### AST
153
146
154−`[%zpts p=hoon]`: make the Nock formula for a Hoon expression.
147+```hoon
148+[%zpts p=hoon]
149+```
155
150
156−##### Produces
151+#### Produces
157
152
158The Nock generated by `p`.
153The Nock generated by `p`.
159
154
160−##### Syntax
161−
162−Regular: **1-fixed**.
163−
164−##### Discussion
155+#### Discussion
165
156
166Don't confuse `!=` with a negation, `!`, followed by a test for equality, `=(10 11)`.
157Don't confuse `!=` with a negation, `!`, followed by a test for equality, `=(10 11)`.
167
158
168−##### Examples
159+#### Examples
169
160
170```
161```
171> !=(20)
162> !=(20)
@@ -188,53 +179,261 @@ Don't confuse the `!=` rune with:
188%.n
179%.n
189```
180```
190
181
191−The syntax difference is that a test for equality takes two subexpressions, and the `!=` rune only one.
182+The syntax difference is that a test for equality takes two subexpressions, and
183+the `!=` rune only one.
192
184
193−### `!?` "zapwut"
185+---
194
186
195−`[%zpwt p=@ q=hoon]`: restrict Hoon version.
187+## `!?` "zapwut"
196
188
197−##### Produces
189+Restrict Hoon version.
198
190
199−`q`, if `p` is greater than or equal to the Hoon kelvin version.
191+#### Syntax
200−(Versions count down; the current version is 140.)
192+
193+Two arguments, fixed.
194+
195+Tall form:
196+
197+```hoon
198+!? p
199+q
200+```
201+
202+Wide form:
203+
204+```hoon
205+!?(p q)
206+```
207+
208+Irregular form:
201
209
202−##### Syntax
210+None.
203
211
204−Regular: **2-fixed**.
212+#### AST
205
213
214+```hoon
215+[%zpwt p=$@(p=@ [p=@ q=@]) q=hoon]
216+```
217+
218+#### Produces
219+
220+When `p` is an atom:
221+
222+- `q` if `p` ≥ Hoon kelvin version, otherwise crash.
223+
224+When `p` is a cell:
225+
226+- `q`, if `p.p` ≥ Hoon kelvin version ≥ `q.p`, otherwise crash.
227+
228+(Versions count down; the current version is 140.)
229+
206−##### Examples
230+#### Examples
207
231
208```
232```
209−> !?(264 (add 2 2))
233+> !? [142 140] (add 2 2)
2104
2344
211
235
212−> !?(164 (add 2 2))
236+> !? 142 (add 2 2)
2134
2374
214
238
215−> !?(64 (add 2 2))
239+> !? 64 (add 2 2)
216! exit
240! exit
217```
241```
218
242
219−### `!!` "zapzap"
243+---
220
244
221−`[%zpzp ~]`: crash.
245+## `!@` "zappat"
222
246
223−##### Produces
247+Branch on whether a wing exists.
224
248
225−Nothing. Always crashes, with type `%void`.
249+#### Syntax
226
250
227−##### Syntax
251+Three arguments, fixed.
228
252
229−`!!`
253+Tall form:
230
254
255+```hoon
256+!@ p
257+ q
258+r
259+```
260+
261+Wide form:
262+
263+```hoon
264+!@(p q r)
265+```
266+
267+Irregular form:
268+
269+None.
270+
271+#### AST
272+
273+```hoon
274+[%zppt p=(list wing) q=hoon r=hoon]
275+```
276+
277+#### Discussion
278+
279+`p` is a wing reference like `foo`, `bar.foo`, etc. If `p` exists, `q`. If `p`
280+does not exist, `r`. Essentially, this is like `?:` for wing existence.
281+
282+#### Examples
283+
284+```
285+> =foo 42
286+
287+> !@(foo 'exists' 'does not exist')
288+'exists'
289+
290+> !@(baz 'exists' 'does not exist')
291+'does not exist'
292+```
293+
294+---
295+
296+## `!!` "zapzap"
297+
298+Crash.
299+
300+#### Syntax
301+
302+No arguments.
303+
304+Tall & wide form:
305+
306+```hoon
307+!!
308+```
309+
310+Irregular form:
311+
312+None.
313+
314+#### AST
315+
316+```hoon
317+[%zpzp ~]
318+```
319+
320+#### Produces
321+
322+Nothing. Always crashes, with type `%void`.
323+
231−##### Discussion
324+#### Discussion
232
325
233`%void` nests in every other type, so you can stub out anything with `!!`.
326`%void` nests in every other type, so you can stub out anything with `!!`.
234
327
235−##### Examples
328+#### Examples
236
329
237```
330```
238> !!
331> !!
239−ford: build failed
332+dojo: hoon expression failed
333+```
334+
335+---
336+
337+## `!:` "zapcol"
338+
339+Turn on stack trace.
340+
341+#### Syntax
342+
343+One argument, fixed
344+
345+Tall form:
346+
347+```hoon
348+!: p
240```
349```
350+
351+Wide form:
352+
353+```hoon
354+!:(p)
355+```
356+
357+Irregular form:
358+
359+None.
360+
361+#### Produces
362+
363+The product of `p` unless `p` crashes, in which case a stack trace is given.
364+
365+#### Discussion
366+
367+`!:` is used to turn on a debugging stack trace option for any code you have in
368+`p`.
369+
370+#### Examples
371+
372+```
373+> ?:(=(0 1) 123 !!)
374+dojo: hoon expression failed
375+
376+> !: ?:(=(0 1) 123 !!)
377+/~zod/base/~2022.4.2..08.54.53..07d7:<[1 5].[1 22]>
378+/~zod/base/~2022.4.2..08.54.53..07d7:<[1 19].[1 21]>
379+dojo: hoon expression failed
380+```
381+
382+---
383+
384+## `!.` "zapdot"
385+
386+Turn off stack trace for a subexpression `p`
387+
388+#### Syntax
389+
390+One argument, fixed.
391+
392+Tall form:
393+
394+```hoon
395+!. p
396+```
397+
398+Wide form:
399+
400+```hoon
401+!.(p)
402+```
403+
404+Irregular form:
405+
406+None.
407+
408+#### Produces
409+
410+The product of `p`. If `p` crashes, no stack trace entries are given for that code.
411+
412+#### Discussion
413+
414+`!.` is used to turn off a debugging stack trace option for any code you have in
415+`p`. This rune can be embedded under a `!:` rune for inner loops of your code
416+that you don't want or need to trace. This is especially useful if a trace
417+overflows the stack.
418+
419+#### Examples
420+
421+```
422+> %.(1 |=(a=@ ^-(@ ?:(=(a 10) !! $(a +(a))))))
423+dojo: hoon expression failed
424+
425+> !: %.(1 |=(a=@ ^-(@ ?:(=(a 10) !! $(a +(a))))))
426+/~zod/base/~2022.4.2..08.56.45..5ecc:<[1 5].[1 49]>
427+/~zod/base/~2022.4.2..08.56.45..5ecc:<[1 17].[1 47]>
428+/~zod/base/~2022.4.2..08.56.45..5ecc:<[1 22].[1 46]>
429+...skipping some lines...
430+/~zod/base/~2022.4.2..08.56.45..5ecc:<[1 22].[1 46]>
431+/~zod/base/~2022.4.2..08.56.45..5ecc:<[1 33].[1 35]>
432+dojo: hoon expression failed
433+
434+> !: %.(1 !.(|=(a=@ ^-(@ ?:(=(a 10) !! $(a +(a)))))))
435+/~zod/base/~2022.4.2..08.57.07..d40b:<[1 5].[1 53]>
436+dojo: hoon expression failed
437+```
438+
439+---
lib/glossary.js+7
@@ -91,6 +91,13 @@ export const glossary = [
91 slug: "/docs/hoon/reference/rune/zap/#-zapwut",
91 slug: "/docs/hoon/reference/rune/zap/#-zapwut",
92 desc: "<code>[%zpwt p=@ q=hoon]</code>: restrict Hoon version.",
92 desc: "<code>[%zpwt p=@ q=hoon]</code>: restrict Hoon version.",
93 },
93 },
94+ {
95+ name: "zappat",
96+ symbol: "!@",
97+ usage: "wild",
98+ slug: "/docs/hoon/reference/rune/zap/#-zappat",
99+ desc: "<code>[%zppt p=(list wing) q=hoon r=hoon]</code>: branch on wing existence.",
100+ },
94 {
101 {
95 name: "zapzap",
102 name: "zapzap",
96 symbol: "!!",
103 symbol: "!!",