@@ -7,13 +7,53 @@ aliases = ["docs/reference/hoon-expressions/rune/mic/"]
77
88Miscellaneous useful macros.
99
10−## Runes
10+## `;:` "miccol"
11+
12+Call a binary function as an n-ary function.
13+
14+#### Syntax
15+
16+One fixed argument, then a variable number of arguments.
17+
18+<table>
19+<tr><th>Form</th><th>Syntax</th></tr>
20+<tr>
21+<td>Tall</td>
22+<td>
23+<pre>
24+;: p
25+ q1
26+ q2
27+ qn
28+==
29+</pre>
30+</td>
31+</tr>
32+<tr>
33+<td>Wide</td>
34+<td>
35+<pre>
36+;:(p q1 q2 qn)
37+</pre>
38+</td>
39+</tr>
40+<tr>
41+<td>Irregular</td>
42+<td>
43+<pre>
44+:(p q1 q2 qn)
45+</pre>
46+</td>
47+</tr>
48+</table>
49+
50+#### AST
1151
12−### `;:` "miccol"
13−
14−`[%mccl p=hoon q=(list hoon)]`: call a binary function as an n-ary function.
52+```hoon
53+[%mccl p=hoon q=(list hoon)]
54+```
1555
16−##### Expands to
56+#### Expands to
1757
1858**Pseudocode**: `a`, `b`, `c`, ... as elements of `q`:
1959
@@ -29,7 +69,7 @@ Irregular form:
2969(p a (p b (p c ...)))
3070```
3171
32−##### Desugaring
72+#### Desugaring
3373
3474```hoon
3575|-
@@ -40,35 +80,57 @@ Irregular form:
4080(p i.q $(q t.q))
4181```
4282
43−##### Syntax
44−
45−Regular: **1-fixed**, then **running**.
46−
47−Irregular: `:(add a b c)` is `;:(add a b c)`.
48−
49−##### Examples
83+#### Examples
5084
5185```
52−~zod:dojo> (add 3 (add 4 5))
86+> (add 3 (add 4 5))
538712
5488
55−~zod:dojo> ;:(add 3 4 5)
89+> ;:(add 3 4 5)
569012
5791
58−~zod:dojo> :(add 3 4 5)
92+> :(add 3 4 5)
599312
94+
95+> `@t`:((cury cat 3) 'a' 'b' 'c' 'd')
96+'abcd'
6097```
6198
62−### `;<` "micgal"
99+---
100+
101+## `;<` "micgal"
102+
103+Monadic do notation.
104+
105+#### Syntax
63106
64−`[%mcgl p=spec q=hoon r=hoon s=hoon]`: monadic do notation.
107+Four arguments, fixed.
65108
66−##### Syntax
109+<table>
110+<tr><th>Form</th><th>Syntax</th></tr>
111+<tr>
112+<td>Tall</td>
113+<td>
114+<pre>
115+;< mold bind expr1 expr2
116+</pre>
117+</td>
118+</tr>
119+<tr>
120+<td>Wide</td>
121+<td>
122+<pre>
123+;<(mold bind expr1 expr2)
124+</pre>
125+</td>
126+</tr>
127+<tr><td>Irregular</td><td>None.</td></tr>
128+</table>
67129
68−Regular: **4-fixed**
130+#### AST
69131
70132```hoon
71−;< mold=mold bind=hoon expr1=hoon expr2=hoon
133+[%mcgl p=spec q=hoon r=hoon s=hoon]
72134```
73135
74136#### Semantics
@@ -77,7 +139,7 @@ A `;<` is for sequencing two computations, `expr1` and `expr2`, using a provided
77139implementation of monadic bind. This rune takes a gate `bind` which takes a mold
78140`mold` and produces an implementation of monadic bind.
79141
80−##### Desugaring
142+#### Desugaring
81143
82144```hoon
83145%+ (bind mold)
@@ -86,7 +148,7 @@ implementation of monadic bind. This rune takes a gate `bind` which takes a mold
86148expr2
87149```
88150
89−##### Discussion
151+#### Discussion
90152
91153`;<` is much like Haskell `do` notation. You have a sequence of events you'd
92154like to run such that each past the first depends on the output of the previous
@@ -103,72 +165,102 @@ external data.
103165
104166We remark that you can switch binds in the middle of a sequence of `;<`.
105167
106−##### Examples
168+#### Examples
107169
108170[`+biff`](/docs/hoon/reference/stdlib/2a/#biff) is the unit monad's
109171implementation of monadic bind. That is to say, it takes a unit `a` and a gate
110172`b` that accepts a noun that produces a unit, and extracts the value from `a` to
111−pass as a sample to `b`.
173+pass as a sample to `b`.
112174
113175We illustrate the usage of `;<` with `+biff` with a `map` of atoms:
176+
114177```
115−~zod:dojo> =m (my ~[[1 3] [2 2] [3 1]])
116− > (~(get by m) 1)
117− [~ 3]
178+> =m (my ~[[1 3] [2 2] [3 1]])
179+> (~(get by m) 1)
180+[~ 3]
118181```
182+
119183A single usage of `;<` only serves to apply the binding function to the output
120184of `expr1`:
185+
121186```
122−~zod:dojo> ;< a=@ _biff (~(get by m) 1)
123− a
124− 3
187+> ;< a=@ _biff (~(get by m) 1)
188+ a
189+3
125190```
191+
126192Here we see the result of chaining them together:
193+
127194```
128−~zod:dojo> ;< a=@ _biff (~(get by m) 1)
129− ;< b=@ _biff (~(get by m) a)
130− b
131− 1
195+> ;< a=@ _biff (~(get by m) 1)
196+ ;< b=@ _biff (~(get by m) a)
197+ b
198+1
132199```
133200
201+---
134202
135−
136−### `;+` "miclus"
203+## `;+` "miclus"
137204
138205make a single XML node (Sail)
139206
140−##### Produces
141−
142−A `marl`, i.e., a list of `manx`. A `manx` is a noun that represents a single XML node.
207+#### Syntax
208+
209+One argument, fixed.
210+
211+<table>
212+<tr><th>Form</th><th>Syntax</th></tr>
213+<tr>
214+<td>Tall</td>
215+<td>
216+<pre>
217+;+ p
218+</pre>
219+</td>
220+</tr>
221+<tr>
222+<td>Wide</td>
223+<td>
224+<pre>
225+;+(p)
226+</pre>
227+</td>
228+</tr>
229+<tr><td>Irregular</td><td>None.</td></tr>
230+</table>
143231
144−##### Syntax
145−
146−**1-fixed**
232+`p` is a Hoon expression that produces a `manx`.
147233
148−```hoon
149−;+ p=hoon
150−```
234+#### Produces
151235
152−`p` is a Hoon expression that produces a `manx`.
236+A [`marl`](/docs/hoon/reference/stdlib/5e#marl), i.e., a list of
237+[`manx`](/docs/hoon/reference/stdlib/5e#manx). A `manx` is a noun that
238+represents a single XML node.
153239
154−##### Discussion
240+#### Discussion
155241
156242tl;dr -- `;+` converts a `manx` to a `marl`.
157243
158−`;+` is a Sail rune. Sail is a part of Hoon used for creating and operating on nouns that represent XML nodes. With the appropriate rendering pipeline, a Sail document can be used to generate a static website.
244+`;+` is a Sail rune. Sail is a part of Hoon used for creating and operating on
245+nouns that represent XML nodes. With the appropriate rendering pipeline, a Sail
246+document can be used to generate a static website.
159247
160−In Sail a single XML node is represented by a `manx`. A single <code><p></code> node `manx` can be produced in the following way:
248+In Sail a single XML node is represented by a `manx`. A single
249+<code><p></code> node `manx` can be produced in the following way:
161250
162251```
163252> ;p: This will be rendered as an XML node.
164253[[%p ~] [[%$ [%$ "This will be rendered as an XML node."] ~] ~] ~]
165254```
166255
167−Sometimes what is needed is a `marl`, i.e., a list of `manx`. To convert a single `manx` to a `marl`, use the `;+` rune.
256+Sometimes what is needed is a `marl`, i.e., a list of `manx`. To convert a
257+single `manx` to a `marl`, use the `;+` rune.
168258
169−One interesting thing about Sail is that it allows you to use complex Hoon expressions to choose from among several nodes to render. The `;+` rune can take such a complex expression.
259+One interesting thing about Sail is that it allows you to use complex Hoon
260+expressions to choose from among several nodes to render. The `;+` rune can take
261+such a complex expression.
170262
171−##### Examples
263+#### Examples
172264
173265```
174266> ^- marl
@@ -192,11 +284,45 @@ One interesting thing about Sail is that it allows you to use complex Hoon expre
192284]
193285```
194286
195−### `;;` "micmic"
287+---
288+
289+## `;;` "micmic"
290+
291+Normalize with a mold, asserting fixpoint.
196292
197−`[%mcmc p=spec q=hoon]`: normalize with a mold, asserting fixpoint.
293+#### Syntax
198294
199−##### Expands to
295+Two arguments, fixed.
296+
297+<table>
298+<tr><th>Form</th><th>Syntax</th></tr>
299+<tr>
300+<td>Tall</td>
301+<td>
302+<pre>
303+;; p
304+q
305+</pre>
306+</td>
307+</tr>
308+<tr>
309+<td>Wide</td>
310+<td>
311+<pre>
312+;;(p q)
313+</pre>
314+</td>
315+</tr>
316+<tr><td>Irregular</td><td>None.</td></tr>
317+</table>
318+
319+#### AST
320+
321+```hoon
322+[%mcmc p=spec q=hoon]
323+```
324+
325+#### Expands to
200326
201327```hoon
202328=+ a=(p q)
@@ -206,68 +332,130 @@ a
206332
207333> Note: the expansion implementation is hygienic -- it doesn't actually add the `a` face to the subject.
208334
209−##### Syntax
210−
211−Regular: **2-fixed**.
212−
213−##### Examples
335+#### Examples
214336
215337Fails because of auras:
216338
217339```
218−~zod:dojo> ^-(tape ~[97 98 99])
340+> ^-(tape ~[97 98 99])
219341mint-nice
342+-need.?(%~ [i=@tD t=""])
343+-have.[@ud @ud @ud %~]
220344nest-fail
221−ford: %slim failed:
222−ford: %ride failed to compute type:
345+dojo: hoon expression failed
223346```
224347
225348Succeeds because molds don't care about auras:
226349
227350```
228−~zod:dojo> ;;(tape ~[97 98 99])
351+> ;;(tape ~[97 98 99])
229352"abc"
230353```
231354
232355Fails because not a fixpoint:
233356
234357```
235−~zod:dojo> ;;(tape [50 51 52])
236−ford: %ride failed to execute:
358+> ;;(tape [50 51 52])
359+dojo: hoon expression failed
237360```
238361
239−### `;/` "micfas"
362+---
363+
364+## `;/` "micfas"
365+
366+Tape as XML element.
240367
241−`[%mcnt p=hoon]`: tape as XML element.
368+#### Syntax
242369
243−##### Expands to
370+One argument, fixed.
371+
372+<table>
373+<tr><th>Form</th><th>Syntax</th></tr>
374+<tr>
375+<td>Tall</td>
376+<td>
377+<pre>
378+;/ p
379+</pre>
380+</td>
381+</tr>
382+<tr>
383+<td>Wide</td>
384+<td>
385+<pre>
386+;/(p)
387+</pre>
388+</td>
389+</tr>
390+<tr><td>Irregular</td><td>None.</td></tr>
391+</table>
392+
393+#### AST
244394
245395```hoon
246−~[%$ ~[%$ 'p']]
396+[%mcnt p=hoon]
247397```
248398
249−##### Examples
399+#### Expands to
250400
401+```hoon
402+~[%$ ~[%$ 'p']]
251403```
252−~zod/try=> ;/ "foo"
253−[[%~. [%~. "foo] ~] ~]
254−```
404+
405+#### Examples
255406
256407```
257−~zod/try=> :/"foo"
258−[[%~. [%~. "foo] ~] ~]
408+> ;/ "foo"
409+[[%~. [%~. "foo"] ~] ~]
259410```
260411
261−### `;~` "micsig"
412+---
413+
414+## `;~` "micsig"
415+
416+Glue a pipeline together with a product-sample adapter.
262417
263−`[%mcsg p=hoon q=(list hoon)]`: glue a pipeline together with a
264−product-sample adapter.
418+#### Syntax
265419
266−##### Produces
420+One fixed argument, then a variable number of arguments.
421+
422+<table>
423+<tr><th>Form</th><th>Syntax</th></tr>
424+<tr>
425+<td>Tall</td>
426+<td>
427+<pre>
428+;~ p
429+ q1
430+ q2
431+ qn
432+==
433+</pre>
434+</td>
435+</tr>
436+<tr>
437+<td>Wide</td>
438+<td>
439+<pre>
440+;~(p q1 q2 qn)
441+</pre>
442+</td>
443+</tr>
444+<tr><td>Irregular</td><td>None.</td></tr>
445+</table>
446+
447+#### AST
448+
449+```hoon
450+[%mcsg p=hoon q=(list hoon)]
451+```
267452
268−The gates in `q` are composed together using the gate `p` as an intermediate function, which transforms a `q` product and a `q` gate into a `q` sample.
453+#### Produces
269454
270−##### Expands to
455+The gates in `q` are composed together using the gate `p` as an intermediate
456+function, which transforms a `q` product and a `q` gate into a `q` sample.
457+
458+#### Expands to
271459
272460**Note: these are structurally correct, but elide some type-system complexity.**
273461
@@ -289,7 +477,7 @@ The gates in `q` are composed together using the gate `p` as an intermediate fun
289477|. (a (c arg) d(+6 arg))
290478```
291479
292−##### Desugaring
480+#### Desugaring
293481
294482```hoon
295483?~ q !!
@@ -301,12 +489,11 @@ The gates in `q` are composed together using the gate `p` as an intermediate fun
301489|. (p (b c) a(,.+6 c))
302490```
303491
304−##### Discussion
492+#### Discussion
305493
306−Apparently `;~` is a "Kleisli arrow." It's also
307−a close cousin of the infamous "monad." Don't let that bother
308−you. Hoon doesn't know anything about category theory,
309−so you don't need to either.
494+Apparently `;~` is a "Kleisli arrow." It's also a close cousin of the infamous
495+"monad." Don't let that bother you. Hoon doesn't know anything about category
496+theory, so you don't need to either.
310497
311498`;~` is often used in parsers, but is not only for parsers.
312499
@@ -315,80 +502,105 @@ nesting the gates in `q`, each is passed individually to `p` with the product
315502of the previous gate, allowing arbitrary filtering, transformation, or
316503conditional application.
317504
318−##### Syntax
319−
320−Regular: **1-fixed**, then **running**.
321−
322−##### Examples
505+#### Examples
323506
324−A simple "parser." `trip` converts a `cord` (atomic string) to
507+A simple "parser." `trip` converts a `cord` (atomic string) to
325508a `tape` (linked string).
326509
327510```
328−~zod:dojo> =cmp |=([a=tape b=$-(char tape)] `tape`?~(a ~ (weld (b i.a) t.a)))
329−~zod:dojo> ;~(cmp trip)
511+> =cmp |=([a=tape b=$-(char tape)] `tape`?~(a ~ (weld (b i.a) t.a)))
512+> ;~(cmp trip)
330513<1.zje {a/@ <409.yxa 110.lxv 1.ztu $151>}>
331−
332514```
333515
334516With just one gate in the pipeline `q`, the glue `p` is unused:
335517
336518```
337−~zod:dojo> (;~(cmp trip) 'a')
519+> (;~(cmp trip) 'a')
338520"a"
339521```
340522
341523But for multiple gates, we need it to connect the pipeline:
342524
343525```
344−~zod:dojo> (;~(cmp trip |=(a=@ ~[a a])) 'a')
526+> (;~(cmp trip |=(a=@ ~[a a])) 'a')
345527"aa"
346−~zod:dojo> (;~(cmp trip |=(a=@ ~[a a])) '')
528+
529+> (;~(cmp trip |=(a=@ ~[a a])) '')
347530""
348531```
349532
350533A more complicated example:
351534
352535```
353−~zod:dojo> (;~(cmp trip ;~(cmp |=(a=@ ~[a a]) |=(a=@ <(dec a)>))) 'b')
536+> (;~(cmp trip ;~(cmp |=(a=@ ~[a a]) |=(a=@ <(dec a)>))) 'b')
354537"97b"
355−~zod:dojo> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) 'b')
538+
539+> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) 'b')
356540"97b"
357−~zod:dojo> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) '')
541+
542+> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) '')
358543""
359−~zod:dojo> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) 'a')
544+
545+> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) 'a')
360546"96a"
361−~zod:dojo> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) 'acd')
547+
548+> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) 'acd')
362549"96acd"
363550```
364551
365−### `;*` "mictar"
552+---
553+
554+## `;*` "mictar"
366555
367556make a list of XML nodes from complex Hoon expression (Sail)
368557
369−##### Produces
558+#### Syntax
559+
560+One argument, fixed.
561+
562+<table>
563+<tr><th>Form</th><th>Syntax</th></tr>
564+<tr>
565+<td>Tall</td>
566+<td>
567+<pre>
568+;* p
569+</pre>
570+</td>
571+</tr>
572+<tr>
573+<td>Wide</td>
574+<td>
575+<pre>
576+;*(p)
577+</pre>
578+</td>
579+</tr>
580+<tr><td>Irregular</td><td>None.</td></tr>
581+</table>
370582
371−A `marl`, i.e., a list of `manx`. A `manx` is a noun that represents a single XML node.
583+`p` is a Hoon expression that produces a `marl`.
372584
373−##### Syntax
585+#### Produces
374586
375−**1-fixed**
587+A [`marl`](/docs/hoon/reference/stdlib/5e#marl), i.e., a list of
588+[`manx`](/docs/hoon/reference/stdlib/5e#manx). A `manx` is a noun that
589+represents a single XML node.
376590
377−```hoon
378−;* p=hoon
379−```
591+#### Discussion
380592
381−`p` is a Hoon expression that produces a `marl`.
593+`;*` is a Sail rune. Sail is a part of Hoon used for creating and operating on
594+nouns that represent XML nodes. With the appropriate rendering pipeline, a Sail
595+document can be used to generate a static website.
382596
383−##### Discussion
384−
385−`;*` is a Sail rune. Sail is a part of Hoon used for creating and operating on nouns that represent XML nodes. With the appropriate rendering pipeline, a Sail document can be used to generate a static website.
386−
387−If you need a complex Hoon expression to produce a `marl`, use the `;*` rune. Often this rune is used with an expression, `p`, that includes one or more `;=` subexpressions.
597+If you need a complex Hoon expression to produce a `marl`, use the `;*` rune.
598+Often this rune is used with an expression, `p`, that includes one or more `;=`
599+subexpressions.
388600
389601(See also [`;=`](#mictis).)
390602
391−##### Examples
603+#### Examples
392604
393605```
394606> ;* ?: (gth 3 2)
@@ -414,40 +626,69 @@ If you need a complex Hoon expression to produce a `marl`, use the `;*` rune. O
414626]
415627```
416628
417−### `;=` "mictis"
418−
419−make a list of XML nodes (Sail)
420−
421−##### Produces
422−
423−A `marl`, i.e., a list of `manx`. A `manx` is a noun that represents a single XML node.
424−
425−##### Syntax
426−
427−**running**
428−
429−```hoon
430−;= p=hoon q=hoon ... z=hoon ==
431−```
432−
433−`p`-`z` are Hoon expressions, each of which poduces a `manx`.
629+---
434630
435−##### Discussion
631+## `;=` "mictis"
436632
437−`;=` is a Sail rune. Sail is a part of Hoon used for creating and operating on nouns that represent XML nodes. With the appropriate rendering pipeline, a Sail document can be used to generate a static website.
633+make a list of XML nodes (Sail)
438634
439−In Sail a single XML node is represented by a `manx`. A single `<p>` node `manx` can be produced in the following way:
635+#### Syntax
636+
637+A variable number of arguments.
638+
639+<table>
640+<tr><th>Form</th><th>Syntax</th></tr>
641+<tr>
642+<td>Tall</td>
643+<td>
644+<pre>
645+;= p1
646+ p2
647+ p3
648+ pn
649+==
650+</pre>
651+</td>
652+</tr>
653+<tr>
654+<td>Wide</td>
655+<td>
656+<pre>
657+;=(p1 p2 p3 pn)
658+</pre>
659+</td>
660+</tr>
661+<tr><td>Irregular</td><td>None.</td></tr>
662+</table>
663+
664+`p1`-`pn` are Hoon expressions, each of which poduces a `manx`.
665+
666+#### Produces
667+
668+A [`marl`](/docs/hoon/reference/stdlib/5e#marl), i.e., a list of
669+[`manx`](/docs/hoon/reference/stdlib/5e#manx). A `manx` is a noun that
670+represents a single XML node.
671+
672+#### Discussion
673+
674+`;=` is a [Sail](/docs/hoon/guides/sail) rune. Sail is a part of Hoon used for
675+creating and operating on nouns that represent XML nodes. With the appropriate
676+rendering pipeline, a Sail document can be used to generate a static website.
677+
678+In Sail a single XML node is represented by a `manx`. A single `<p>` node `manx`
679+can be produced in the following way:
440680
441681```
442682> ;p: This will be rendered as an XML node.
443683[[%p ~] [[%$ [%$ "This will be rendered as an XML node."] ~] ~] ~]
444684```
445685
446−Sometimes what is needed is a `marl`, i.e., a list of `manx`. To convert a series of `manx` nodes to a `marl`, use the `;=` rune.
686+Sometimes what is needed is a `marl`, i.e., a list of `manx`. To convert a
687+series of `manx` nodes to a `marl`, use the `;=` rune.
447688
448689(See also [`;*`](#mictar).)
449690
450−##### Examples
691+#### Examples
451692
452693```
453694> ;= ;p: This is the first node.