@@ -4,242 +4,403 @@ weight = 9
44template = "doc.html"
55aliases = ["docs/reference/hoon-expressions/rune/col/"]
66+++
7−The `:` ("col") expressions are used to produce cells, which are pairs of values. E.g., `:-(p q)` produces the cell `[p q]`. All `:` runes reduce to `:-`.
87
9−## Runes
8+The `:` ("col") expressions are used to produce cells, which are pairs of
9+values. E.g., `:-(p q)` produces the cell `[p q]`. All `:` runes reduce to `:-`.
1010
11−### `:_` "colcab"
11+## `:-` "colhep"
1212
13−`[%clcb p=hoon q=hoon]`; construct a cell, inverted.
13+Construct a cell (2-tuple).
1414
15−##### Expands to
15+#### Syntax
16+
17+Two arguments, fixed.
18+
19+Tall form:
1620
1721```hoon
18−:-(q p)
22+:- p
23+q
1924```
2025
21−##### Syntax
26+Wide form:
2227
23−Regular: **2-fixed**.
28+```hoon
29+:-(p q)
30+```
2431
25−##### Examples
32+Irregular form:
2633
34+```hoon
35+[p q]
2736```
28−~zod:dojo> :_(1 2)
29−[2 1]
37+
38+or
39+
40+```hoon
41+p^q
3042```
3143
32−### `::` "colcol"
44+#### AST
3345
34−Code comment
46+```hoon
47+[%clhp p=hoon q=hoon]
48+```
3549
36−##### Syntax
50+#### Produces
3751
38−:: any text you like!
52+The cell of `p` and `q`.
53+
54+#### Discussion
55+
56+Hoon expressions actually use the same "autocons" pattern as Nock
57+formulas. If you're assembling expressions (which usually only the
58+compiler does), `[a b]` is the same as `:-(a b)`.
59+
60+#### Examples
3961
40−##### Examples
62+```
63+> :-(1 2)
64+[1 2]
65+
66+~zod:dojo> 1^2
67+[1 2]
68+```
69+
70+---
71+
72+## `:_` "colcab"
73+
74+Construct a cell, inverted.
75+
76+#### Syntax
77+
78+Two arguments, fixed.
79+
80+Tall form:
4181
4282```hoon
43−::
44−:: this is commented code
45−::
46−|= a=@ :: a gate
47−(add 2 a) :: that adds 2
48− :: to the input
83+:_ p
84+q
4985```
5086
51−### `:-` "colhep"
87+Wide form:
5288
53−`[%clhp p=hoon q=hoon]`: construct a cell (2-tuple).
89+```hoon
90+:_(p q)
91+```
5492
55−##### Produces
93+Irregular form:
5694
57−The cell of `p` and `q`.
95+None.
5896
59−##### Syntax
97+#### AST
6098
61−Regular: **2-fixed**.
99+```hoon
100+[%clcb p=hoon q=hoon]
101+```
62102
63−Irregular: `[a b]` is `:-(a b)`.
103+#### Expands to
64104
65−Irregular: `[a b c]` is `[a [b c]]`.
105+```hoon
106+:-(q p)
107+```
66108
67−Irregular: `a^b^c` is `[a b c]`.
109+#### Examples
68110
69−Irregular: `a/b` is `[%a b]`.
111+```
112+> :_(1 2)
113+[2 1]
114+```
70115
71−Irregular: `` `a `` is `[~ a]`.
116+---
72117
73−Irregular: `~[a b]` is `[a b ~]`.
118+## `:+` "collus"
74119
75−Irregular: `[a b c]~` is `[[a b c] ~]`.
120+Construct a triple (3-tuple).
76121
77−## Discussion
122+#### Syntax
78123
79−Hoon expressions actually use the same "autocons" pattern as Nock
80−formulas. If you're assembling expressions (which usually only the
81−compiler does), `[a b]` is the same as `:-(a b)`.
124+Three arguments, fixed.
82125
83−##### Examples
126+Tall form:
84127
128+```hoon
129+:+ p
130+ q
131+r
85132```
86−~zod:dojo> :-(1 2)
87−[1 2
88133
89−~zod:dojo> 1^2
90−[1 2]
134+Wide form:
91135
92−~zod:dojo> 1/2
93−[%1 2]
136+```hoon
137+:+(p q r)
138+```
94139
95−~zod:dojo> `1
96−[~ 1]
140+Irregular form:
141+
142+```hoon
143+[p q r]
97144```
98145
99−### `:^` "colket"
146+#### AST
100147
101−`[%clkt p=hoon q=hoon r=hoon s=hoon]`: construct a quadruple (4-tuple).
148+```hoon
149+[%clls p=hoon q=hoon r=hoon]
150+```
102151
103−##### Expands to
152+#### Expands to:
104153
105154```hoon
106−:-(p :-(q :-(r s)))
155+:-(p :-(q r))
107156```
108157
109−##### Syntax
158+#### Examples
110159
111−Regular: **4-fixed**.
160+```
161+> :+ 1
162+ 2
163+ 3
164+[1 2 3]
165+
166+> :+(%a ~ 'b')
167+[%a ~ 'b']
168+```
169+
170+---
112171
113−##### Examples
172+## `:^` "colket"
114173
174+Construct a quadruple (4-tuple).
175+
176+#### Syntax
177+
178+Four arguments, fixed.
179+
180+Tall form:
181+
182+```hoon
183+:^ p
184+ q
185+ r
186+s
115187```
116−~zod:dojo> :^(1 2 3 4)
117−[1 2 3 4]
118188
119−~zod:dojo> :^ 5
120− 6
121− 7
122− 8
123−[5 6 7 8]
189+Wide form:
190+
191+```hoon
192+:^(p q r s)
124193```
125194
126−### `:+` "collus"
195+Irregular form:
196+
197+```hoon
198+[p q r s]
199+```
127200
201+#### AST
128202
129−`[%clls p=hoon q=hoon r=hoon]`: construct a triple (3-tuple).
203+```hoon
204+[%clkt p=hoon q=hoon r=hoon s=hoon]
205+```
130206
131−##### Expands to:
207+#### Expands to
132208
133209```hoon
134−:-(p :-(q r))
210+:-(p :-(q :-(r s)))
211+```
212+
213+#### Examples
214+
135215```
216+> :^(1 2 3 4)
217+[1 2 3 4]
218+
219+> :^ 5
220+ 6
221+ 7
222+ 8
223+[5 6 7 8]
224+```
225+
226+---
227+
228+## `:*` "coltar"
229+
230+Construct an n-tuple.
136231
137−##### Syntax
232+#### Syntax
138233
139−Regular: **3-fixed**.
234+Variable number of arguments.
140235
141−##### Examples
236+Tall form:
142237
238+```hoon
239+:* p1
240+ p2
241+ p3
242+ pn
243+==
143244```
144−/~zod:dojo> :+ 1
145− 2
146− 3
147−[1 2 3]
148245
149−~zod:dojo> :+(%a ~ 'b')
150−[%a ~ 'b']
246+Wide form:
247+
248+```hoon
249+:*(p1 p2 p3 pn)
151250```
152251
153−### `:~` "colsig"
252+Irregular form:
154253
155−`[%clsg p=(list hoon)]`: construct a null-terminated list.
254+```hoon
255+[p1 p2 p3 pn]
256+```
257+
258+#### AST
156259
157−##### Expands to
260+```hoon
261+[%cltr p=(list hoon)]
262+```
263+
264+#### Expands to
158265
159266**Pseudocode**: `a`, `b`, `c`, ... as elements of `p`:
160267
161268```hoon
162−:-(a :-(b :-(c :-(... :-(z ~)))))
269+:-(a :-(b :-(c :-(... z)))))
163270```
164271
165−##### Desugaring
272+#### Desugaring
166273
167274```hoon
168275|-
169276?~ p
170− ~
277+ !!
278+?~ t.p
279+ i.p
171280:- i.p
172281$(p t.p)
173282```
174283
175−##### Syntax
284+#### Examples
176285
177−Regular: **running**.
286+```
287+> :*(5 3 4 1 4 9 0 ~ 'a')
288+[5 3 4 1 4 9 0 ~ 'a']
178289
179−##### Examples
290+> [5 3 4 1 4 9 0 ~ 'a']
291+[5 3 4 1 4 9 0 ~ 'a']
180292
293+> :* 5
294+ 3
295+ 4
296+ 1
297+ 4
298+ 9
299+ 0
300+ ~
301+ 'a'
302+ ==
303+[5 3 4 1 4 9 0 ~ 'a']
181304```
182−~zod:dojo> :~(5 3 4 2 1)
183−[5 3 4 2 1 ~]
184305
185−~zod:dojo> ~[5 3 4 2 1]
186−[5 3 4 2 1 ~]
306+---
187307
188−~zod:dojo> :~ 5
189− 3
190− 4
191− 2
192− 1
193− ==
194−[5 3 4 2 1 ~]
308+## `:~` "colsig"
309+
310+Construct a null-terminated list.
311+
312+#### Syntax
313+
314+Variable number of arguments.
315+
316+Tall form:
317+
318+```hoon
319+:~ p1
320+ p2
321+ p3
322+ pn
323+==
195324```
196325
197−### `:*` "coltar"
326+Wide form:
198327
199−`[%cltr p=(list hoon)]`: construct an n-tuple.
328+```hoon
329+:~(p1 p2 p3 pn)
330+```
331+
332+Irregular form:
333+
334+```hoon
335+~[p1 p2 p3 pn]
336+```
337+
338+#### AST
339+
340+```hoon
341+[%clsg p=(list hoon)]
342+```
200343
201−##### Expands to
344+#### Expands to
202345
203346**Pseudocode**: `a`, `b`, `c`, ... as elements of `p`:
204347
205348```hoon
206−:-(a :-(b :-(c :-(... z)))))
349+:-(a :-(b :-(c :-(... :-(z ~)))))
207350```
208351
209−##### Desugaring
352+#### Desugaring
210353
211354```hoon
212355|-
213356?~ p
214− !!
215−?~ t.p
216− i.p
357+ ~
217358:- i.p
218359$(p t.p)
219360```
220361
221−##### Syntax
362+#### Discussion
222363
223−Regular: **running**.
364+Note that this does not produce a `list` type, it just produces a
365+null-terminated n-tuple. To make it a proper `list` it must be cast or molded.
224366
225−##### Examples
367+#### Examples
226368
227369```
228−~zod:dojo> :*(5 3 4 1 4 9 0 ~ 'a')
229−[5 3 4 1 4 9 0 ~ 'a']
370+> :~(5 3 4 2 1)
371+[5 3 4 2 1 ~]
230372
231−~zod:dojo> [5 3 4 1 4 9 0 ~ 'a']
232−[5 3 4 1 4 9 0 ~ 'a']
373+> ~[5 3 4 2 1]
374+[5 3 4 2 1 ~]
233375
234−~zod:dojo> :* 5
235− 3
236− 4
237− 1
238− 4
239− 9
240− 0
241− ~
242− 'a'
243− ==
244−[5 3 4 1 4 9 0 ~ 'a']
376+> :~ 5
377+ 3
378+ 4
379+ 2
380+ 1
381+ ==
382+[5 3 4 2 1 ~]
383+```
384+
385+---
386+
387+## `::` "colcol"
388+
389+Code comment.
390+
391+#### Syntax
392+
393+```hoon
394+:: any text you like!
395+```
396+
397+#### Examples
398+
399+```hoon
400+::
401+:: this is commented code
402+::
403+|= a=@ :: a gate
404+(add 2 a) :: that adds 2
405+ :: to the input
245406```