git.iko.soy/urbit.org
on master help sign in
Merge pull request #1044 from urbit/micgal
737ee6cpoprox
hoon/reference/rune/mic.md+74
compare with master
unifiedsplit
@@ -59,6 +59,80 @@ Irregular: `:(add a b c)` is `;:(add a b c)`.
5912
5912
60```
60```
61
61
62+### `;<` "micgal"
63+
64+`[%mcgl p=spec q=hoon r=hoon s=hoon]`: monadic do notation.
65+
66+##### Syntax
67+
68+Regular: **4-fixed**
69+
70+```hoon
71+;< mold=mold bind=hoon expr1=hoon expr2=hoon
72+```
73+
74+#### Semantics
75+
76+A `;<` is for sequencing two computations, `expr1` and `expr2`, using a provided
77+implementation of monadic bind. This rune takes a gate `bind` which takes a mold
78+`mold` and produces an implementation of monadic bind.
79+
80+##### Desugaring
81+
82+```hoon
83+%+ (bind mold)
84+ expr1
85+|= mold
86+expr2
87+```
88+
89+##### Discussion
90+
91+`;<` is much like Haskell `do` notation. You have a sequence of events you'd
92+like to run such that each past the first depends on the output of the previous
93+one. The output of the previous one may not be of the correct type to use as an
94+input to the next one, and so an adapter such as `+biff` is needed.
95+
96+`;<` differs from [`;~`](#micsig) in that it takes a gate which takes a mold
97+that produces an implementation of monadic bind, rather than taking an
98+implementation of monadic bind directly.
99+
100+`;<` can be used to glue a pipeline together to run an asynchronous function or
101+event. This can be helpful when deferring parts of a computation based on
102+external data.
103+
104+We remark that you can switch binds in the middle of a sequence of `;<`.
105+
106+##### Examples
107+
108+[`+biff`](@/docs/hoon/reference/stdlib/2a/#biff) is the unit monad's
109+implementation 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
111+pass as a sample to `b`.
112+
113+We illustrate the usage of `;<` with `+biff` with a `map` of atoms:
114+```
115+~zod:dojo> =m (my ~[[1 3] [2 2] [3 1]])
116+ > (~(get by m) 1)
117+ [~ 3]
118+```
119+A single usage of `;<` only serves to apply the binding function to the output
120+of `expr1`:
121+```
122+~zod:dojo> ;< a=@ _biff (~(get by m) 1)
123+ a
124+ 3
125+```
126+Here we see the result of chaining them together:
127+```
128+~zod:dojo> ;< a=@ _biff (~(get by m) 1)
129+ ;< b=@ _biff (~(get by m) a)
130+ b
131+ 1
132+```
133+
134+
135+
62### `;+` "miclus"
136### `;+` "miclus"
63
137
64make a single XML node (Sail)
138make a single XML node (Sail)