@@ -7,13 +7,53 @@ aliases = ["docs/reference/hoon-expressions/rune/mic/"]
8Miscellaneous useful macros.
8Miscellaneous useful macros.
10−## Runes
10+## `;:` "miccol"
12+Call a binary function as an n-ary function.
16+One fixed argument, then a variable number of arguments.
19+<tr><th>Form</th><th>Syntax</th></tr>
12−### `;:` "miccol"
52+```hoon
14−`[%mccl p=hoon q=(list hoon)]`: call a binary function as an n-ary function.
53+[%mccl p=hoon q=(list hoon)]
16−##### Expands to
56+#### Expands to
18**Pseudocode**: `a`, `b`, `c`, ... as elements of `q`:
58**Pseudocode**: `a`, `b`, `c`, ... as elements of `q`:
@@ -29,7 +69,7 @@ Irregular form:
29(p a (p b (p c ...)))
69(p a (p b (p c ...)))
32−##### Desugaring
72+#### Desugaring
@@ -40,35 +80,57 @@ Irregular form:
40(p i.q $(q t.q))
80(p i.q $(q t.q))
45−Regular: **1-fixed**, then **running**.
47−Irregular: `:(add a b c)` is `;:(add a b c)`.
49−##### Examples
83+#### Examples
52−~zod:dojo> (add 3 (add 4 5))
86+> (add 3 (add 4 5))
55−~zod:dojo> ;:(add 3 4 5)
89+> ;:(add 3 4 5)
58−~zod:dojo> :(add 3 4 5)
92+> :(add 3 4 5)
95+> `@t`:((cury cat 3) 'a' 'b' 'c' 'd')
62−### `;<` "micgal"
101+## `;<` "micgal"
64−`[%mcgl p=spec q=hoon r=hoon s=hoon]`: monadic do notation.
107+Four arguments, fixed.
66−##### Syntax
110+<tr><th>Form</th><th>Syntax</th></tr>
115+;< mold bind expr1 expr2
123+;<(mold bind expr1 expr2)
127+<tr><td>Irregular</td><td>None.</td></tr>
68−Regular: **4-fixed**
130+#### AST
71−;< mold=mold bind=hoon expr1=hoon expr2=hoon
133+[%mcgl p=spec q=hoon r=hoon s=hoon]
74#### Semantics
136#### Semantics
@@ -77,7 +139,7 @@ A `;<` is for sequencing two computations, `expr1` and `expr2`, using a provided
77implementation of monadic bind. This rune takes a gate `bind` which takes a mold
139implementation of monadic bind. This rune takes a gate `bind` which takes a mold
78`mold` and produces an implementation of monadic bind.
140`mold` and produces an implementation of monadic bind.
80−##### Desugaring
142+#### Desugaring
83%+ (bind mold)
145%+ (bind mold)
@@ -86,7 +148,7 @@ implementation of monadic bind. This rune takes a gate `bind` which takes a mold
89−##### Discussion
151+#### Discussion
91`;<` is much like Haskell `do` notation. You have a sequence of events you'd
153`;<` is much like Haskell `do` notation. You have a sequence of events you'd
92like to run such that each past the first depends on the output of the previous
154like to run such that each past the first depends on the output of the previous
@@ -103,72 +165,102 @@ external data.
104We remark that you can switch binds in the middle of a sequence of `;<`.
166We remark that you can switch binds in the middle of a sequence of `;<`.
106−##### Examples
168+#### Examples
108[`+biff`](/docs/hoon/reference/stdlib/2a/#biff) is the unit monad's
170[`+biff`](/docs/hoon/reference/stdlib/2a/#biff) is the unit monad's
109implementation of monadic bind. That is to say, it takes a unit `a` and a gate
171implementation of monadic bind. That is to say, it takes a unit `a` and a gate
110`b` that accepts a noun that produces a unit, and extracts the value from `a` to
172`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`.
113We illustrate the usage of `;<` with `+biff` with a `map` of atoms:
175We illustrate the usage of `;<` with `+biff` with a `map` of atoms:
115−~zod:dojo> =m (my ~[[1 3] [2 2] [3 1]])
178+> =m (my ~[[1 3] [2 2] [3 1]])
116− > (~(get by m) 1)
179+> (~(get by m) 1)
119A single usage of `;<` only serves to apply the binding function to the output
183A single usage of `;<` only serves to apply the binding function to the output
120of `expr1`:
184of `expr1`:
122−~zod:dojo> ;< a=@ _biff (~(get by m) 1)
187+> ;< a=@ _biff (~(get by m) 1)
126Here we see the result of chaining them together:
192Here we see the result of chaining them together:
128−~zod:dojo> ;< a=@ _biff (~(get by m) 1)
195+> ;< a=@ _biff (~(get by m) 1)
129− ;< b=@ _biff (~(get by m) a)
196+ ;< b=@ _biff (~(get by m) a)
136−### `;+` "miclus"
203+## `;+` "miclus"
138make a single XML node (Sail)
205make a single XML node (Sail)
140−##### Produces
207+#### Syntax
142−A `marl`, i.e., a list of `manx`. A `manx` is a noun that represents a single XML node.
209+One argument, fixed.
212+<tr><th>Form</th><th>Syntax</th></tr>
229+<tr><td>Irregular</td><td>None.</td></tr>
144−##### Syntax
232+`p` is a Hoon expression that produces a `manx`.
148−```hoon
234+#### Produces
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.
154−##### Discussion
240+#### Discussion
156tl;dr -- `;+` converts a `manx` to a `marl`.
242tl;dr -- `;+` converts a `manx` to a `marl`.
244+`;+` is a Sail rune. Sail is a part of Hoon used for creating and operating on
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.
245+nouns that represent XML nodes. With the appropriate rendering pipeline, a Sail
246+document can be used to generate a static website.
248+In Sail a single XML node is represented by a `manx`. A single
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:
249+<code><p></code> node `manx` can be produced in the following way:
163> ;p: This will be rendered as an XML node.
252> ;p: This will be rendered as an XML node.
164[[%p ~] [[%$ [%$ "This will be rendered as an XML node."] ~] ~] ~]
253[[%p ~] [[%$ [%$ "This will be rendered as an XML node."] ~] ~] ~]
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.
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.
171−##### Examples
263+#### Examples
@@ -192,11 +284,45 @@ One interesting thing about Sail is that it allows you to use complex Hoon expre
195−### `;;` "micmic"
289+## `;;` "micmic"
291+Normalize with a mold, asserting fixpoint.
197−`[%mcmc p=spec q=hoon]`: normalize with a mold, asserting fixpoint.
293+#### Syntax
295+Two arguments, fixed.
298+<tr><th>Form</th><th>Syntax</th></tr>
316+<tr><td>Irregular</td><td>None.</td></tr>
322+[%mcmc p=spec q=hoon]
199−##### Expands to
325+#### Expands to
202=+ a=(p q)
328=+ a=(p q)
@@ -206,68 +332,130 @@ a
207> Note: the expansion implementation is hygienic -- it doesn't actually add the `a` face to the subject.
333> Note: the expansion implementation is hygienic -- it doesn't actually add the `a` face to the subject.
211−Regular: **2-fixed**.
213−##### Examples
335+#### Examples
215Fails because of auras:
337Fails because of auras:
218−~zod:dojo> ^-(tape ~[97 98 99])
340+> ^-(tape ~[97 98 99])
342+-need.?(%~ [i=@tD t=""])
343+-have.[@ud @ud @ud %~]
221−ford: %slim failed:
345+dojo: hoon expression failed
222−ford: %ride failed to compute type:
225Succeeds because molds don't care about auras:
348Succeeds because molds don't care about auras:
228−~zod:dojo> ;;(tape ~[97 98 99])
351+> ;;(tape ~[97 98 99])
232Fails because not a fixpoint:
355Fails because not a fixpoint:
235−~zod:dojo> ;;(tape [50 51 52])
358+> ;;(tape [50 51 52])
236−ford: %ride failed to execute:
359+dojo: hoon expression failed
239−### `;/` "micfas"
364+## `;/` "micfas"
241−`[%mcnt p=hoon]`: tape as XML element.
368+#### Syntax
243−##### Expands to
370+One argument, fixed.
373+<tr><th>Form</th><th>Syntax</th></tr>
390+<tr><td>Irregular</td><td>None.</td></tr>
246−~[%$ ~[%$ 'p']]
396+[%mcnt p=hoon]
249−##### Examples
399+#### Expands to
252−~zod/try=> ;/ "foo"
404+
253−[[%~. [%~. "foo] ~] ~]
405+#### Examples
257−~zod/try=> :/"foo"
408+> ;/ "foo"
258−[[%~. [%~. "foo] ~] ~]
409+[[%~. [%~. "foo"] ~] ~]
261−### `;~` "micsig"
414+## `;~` "micsig"
416+Glue a pipeline together with a product-sample adapter.
263−`[%mcsg p=hoon q=(list hoon)]`: glue a pipeline together with a
418+#### Syntax
264−product-sample adapter.
266−##### Produces
420+One fixed argument, then a variable number of arguments.
423+<tr><th>Form</th><th>Syntax</th></tr>
444+<tr><td>Irregular</td><td>None.</td></tr>
450+[%mcsg p=hoon q=(list hoon)]
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
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.
270−##### Expands to
458+#### Expands to
272**Note: these are structurally correct, but elide some type-system complexity.**
460**Note: these are structurally correct, but elide some type-system complexity.**
@@ -289,7 +477,7 @@ The gates in `q` are composed together using the gate `p` as an intermediate fun
289|. (a (c arg) d(+6 arg))
477|. (a (c arg) d(+6 arg))
292−##### Desugaring
480+#### Desugaring
@@ -301,12 +489,11 @@ The gates in `q` are composed together using the gate `p` as an intermediate fun
301|. (p (b c) a(,.+6 c))
489|. (p (b c) a(,.+6 c))
304−##### Discussion
492+#### Discussion
306−Apparently `;~` is a "Kleisli arrow." It's also
494+Apparently `;~` is a "Kleisli arrow." It's also a close cousin of the infamous
307−a close cousin of the infamous "monad." Don't let that bother
308−you. Hoon doesn't know anything about category theory,
495+"monad." Don't let that bother you. Hoon doesn't know anything about category
309−so you don't need to either.
496+theory, so you don't need to either.
311`;~` is often used in parsers, but is not only for parsers.
498`;~` is often used in parsers, but is not only for parsers.
@@ -315,80 +502,105 @@ nesting the gates in `q`, each is passed individually to `p` with the product
315of the previous gate, allowing arbitrary filtering, transformation, or
502of the previous gate, allowing arbitrary filtering, transformation, or
316conditional application.
503conditional application.
320−Regular: **1-fixed**, then **running**.
322−##### Examples
505+#### Examples
324−A simple "parser." `trip` converts a `cord` (atomic string) to
507+A simple "parser." `trip` converts a `cord` (atomic string) to
325a `tape` (linked string).
508a `tape` (linked string).
328−~zod:dojo> =cmp |=([a=tape b=$-(char tape)] `tape`?~(a ~ (weld (b i.a) t.a)))
511+> =cmp |=([a=tape b=$-(char tape)] `tape`?~(a ~ (weld (b i.a) t.a)))
329−~zod:dojo> ;~(cmp trip)
512+> ;~(cmp trip)
330<1.zje {a/@ <409.yxa 110.lxv 1.ztu $151>}>
513<1.zje {a/@ <409.yxa 110.lxv 1.ztu $151>}>
334With just one gate in the pipeline `q`, the glue `p` is unused:
516With just one gate in the pipeline `q`, the glue `p` is unused:
337−~zod:dojo> (;~(cmp trip) 'a')
519+> (;~(cmp trip) 'a')
341But for multiple gates, we need it to connect the pipeline:
523But for multiple gates, we need it to connect the pipeline:
344−~zod:dojo> (;~(cmp trip |=(a=@ ~[a a])) 'a')
526+> (;~(cmp trip |=(a=@ ~[a a])) 'a')
346−~zod:dojo> (;~(cmp trip |=(a=@ ~[a a])) '')
529+> (;~(cmp trip |=(a=@ ~[a a])) '')
350A more complicated example:
533A more complicated example:
353−~zod:dojo> (;~(cmp trip ;~(cmp |=(a=@ ~[a a]) |=(a=@ <(dec a)>))) 'b')
536+> (;~(cmp trip ;~(cmp |=(a=@ ~[a a]) |=(a=@ <(dec a)>))) 'b')
355−~zod:dojo> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) 'b')
539+> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) 'b')
357−~zod:dojo> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) '')
542+> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) '')
359−~zod:dojo> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) 'a')
545+> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) 'a')
361−~zod:dojo> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) 'acd')
548+> (;~(cmp trip |=(a=@ ~[a a]) |=(a=@ <(dec a)>)) 'acd')
365−### `;*` "mictar"
554+## `;*` "mictar"
367make a list of XML nodes from complex Hoon expression (Sail)
556make a list of XML nodes from complex Hoon expression (Sail)
369−##### Produces
558+#### Syntax
563+<tr><th>Form</th><th>Syntax</th></tr>
580+<tr><td>Irregular</td><td>None.</td></tr>
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`.
373−##### Syntax
585+#### Produces
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.
377−```hoon
591+#### Discussion
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.
383−##### Discussion
597+If you need a complex Hoon expression to produce a `marl`, use the `;*` rune.
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.
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.
598+Often this rune is used with an expression, `p`, that includes one or more `;=`
389(See also [`;=`](#mictis).)
601(See also [`;=`](#mictis).)
391−##### Examples
603+#### Examples
394> ;* ?: (gth 3 2)
606> ;* ?: (gth 3 2)
@@ -414,40 +626,69 @@ If you need a complex Hoon expression to produce a `marl`, use the `;*` rune. O
417−### `;=` "mictis"
629+---
419−make a list of XML nodes (Sail)
423−A `marl`, i.e., a list of `manx`. A `manx` is a noun that represents a single XML node.
430−;= p=hoon q=hoon ... z=hoon ==
433−`p`-`z` are Hoon expressions, each of which poduces a `manx`.
435−##### Discussion
631+## `;=` "mictis"
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)
637+A variable number of arguments.
640+<tr><th>Form</th><th>Syntax</th></tr>
661+<tr><td>Irregular</td><td>None.</td></tr>
664+`p1`-`pn` are Hoon expressions, each of which poduces a `manx`.
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.
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.
439−In Sail a single XML node is represented by a `manx`. A single `<p>` node `manx` can be produced in the following way:
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:
442> ;p: This will be rendered as an XML node.
682> ;p: This will be rendered as an XML node.
443[[%p ~] [[%$ [%$ "This will be rendered as an XML node."] ~] ~] ~]
683[[%p ~] [[%$ [%$ "This will be rendered as an XML node."] ~] ~] ~]
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.
448(See also [`;*`](#mictar).)
689(See also [`;*`](#mictar).)
450−##### Examples
691+#### Examples
453> ;= ;p: This is the first node.
694> ;= ;p: This is the first node.