@@ -7,17 +7,53 @@ aliases = ["docs/reference/hoon-expressions/rune/dot/"]
77
88Anything Nock can do, Hoon can do also. These runes are used for carrying out Nock operations in Hoon.
99
10−## Runes
10+## `.^` "dotket"
1111
12−### `.^` "dotket"
12+Load from the Arvo namespace (scry) with a fake Nock instruction: Nock 12.
1313
14−`[%dtkt p=spec q=hoon]`: load from the Arvo namespace with a fake Nock instruction: 'Nock `12`''.
14+#### AST
1515
16−##### Produces
16+```hoon
17+[%dtkt p=spec q=hoon]
18+```
19+
20+#### Produces
1721
1822The noun `q`, cast to the type `p`.
1923
20−##### Discussion
24+#### Regular syntax
25+
26+Two arguments, with the second optionally split into an arbitrary number of
27+elements.
28+
29+While this rune technically takes a fixed number of arguments, `q` is usually
30+split into at least two parts, and the tall form of this rune must be terminated
31+with a `==`. Note also that the `==` does not make the arguments into a list as
32+you might expect, so `q` must be explicitly null-terminated if its elements are
33+specified separately.
34+
35+Tall-form:
36+
37+```hoon
38+.^ p
39+ q-1
40+ q-2
41+ q-3
42+ q-n
43+==
44+```
45+
46+Wide-form:
47+
48+```hoon
49+.^(p q-1 q-2)
50+```
51+
52+#### Irregular syntax
53+
54+None.
55+
56+#### Discussion
2157
2258Nock has no `12` instruction! But the virtual Nock
2359used to run userspace code does. Nock `12` loads from a
@@ -29,7 +65,7 @@ Ordinarily a Hoon expression has access to no information but whatever can be fo
2965
3066In principle `.^` takes two subexpressions, but in practice `q` is often given in two parts: the first part includes the vane to be queried (e.g., `%a` for Ames, `%b` for Behn, `%c` for Clay, etc.) and the kind of request. The second part is a path that corresponds to the kind of request.
3167
32−##### Examples
68+#### Examples
3369
3470In the dojo we can ask Clay -- the Arvo filesystem -- for a listing of the files at our current path, `%`:
3571
@@ -37,17 +73,14 @@ In the dojo we can ask Clay -- the Arvo filesystem -- for a listing of the files
3773> .^(arch %cy %)
3874[ fil=~
3975 dir
40− { [p=~.web q=~]
41− [p=~.LICENSE q=~]
42− [p=~.app q=~]
43− [p=~.lib q=~]
44− [p=~.sec q=~]
45− [p=~.sys q=~]
46− [p=~.ren q=~]
76+ { [p=~.app q=~]
4777 [p=~.sur q=~]
48− [p=~.tests q=~]
49− [p=~.mar q=~]
5078 [p=~.gen q=~]
79+ [p=~.lib q=~]
80+ [p=~.mar q=~]
81+ [p=~.ted q=~]
82+ [p=~.desk q=~]
83+ [p=~.sys q=~]
5184 }
5285]
5386```
@@ -67,38 +100,57 @@ You can modify the time of the file listing quite simply and ask for a listing f
67100> .^(arch %cy /(scot %p our)/base/(scot %da (sub now ~h5)))
68101[ fil=~
69102 dir
70− { [p=~.web q=~]
71− [p=~.LICENSE q=~]
72− [p=~.app q=~]
73− [p=~.lib q=~]
74− [p=~.sec q=~]
75− [p=~.sys q=~]
76− [p=~.ren q=~]
103+ { [p=~.app q=~]
77104 [p=~.sur q=~]
78− [p=~.tests q=~]
79− [p=~.mar q=~]
80105 [p=~.gen q=~]
106+ [p=~.lib q=~]
107+ [p=~.mar q=~]
108+ [p=~.ted q=~]
109+ [p=~.desk q=~]
110+ [p=~.sys q=~]
81111 }
82112]
83113```
84114
85115`our` is the value for your ship's name.
86116
87−### `.+` "dotlus"
117+## `.+` "dotlus"
88118
89−`[%dtls p=hoon]`: increment an atom with Nock `4`.
119+Increment an atom with Nock `4`.
90120
91−##### Produces
121+#### AST
122+
123+```hoon
124+[%dtls p=hoon]
125+```
126+
127+#### Produces
92128
93129`p` plus `1` if `p` is an atom; otherwise, crashes. The product atom has no aura.
94130
95−##### Syntax
131+#### Regular syntax
132+
133+One argument, fixed.
134+
135+Tall-form:
136+
137+```hoon
138+.+ p
139+```
140+
141+Wide-form:
142+
143+```hoon
144+.+(p)
145+```
96146
97−Regular: **1-fixed**.
147+#### Irregular syntax
98148
99−Irregular: `+(6)` is `.+(6)`.
149+```hoon
150++(p)
151+```
100152
101−##### Examples
153+#### Examples
102154
103155```
104156> .+(6)
@@ -114,19 +166,38 @@ Irregular: `+(6)` is `.+(6)`.
114166nest-fail
115167```
116168
117−### `.*` "dottar"
169+## `.*` "dottar"
170+
171+Evaluate with Nock `2`.
118172
119−`[%dttr p=hoon q=hoon]`: evaluate with Nock `2`.
173+#### AST
174+
175+```hoon
176+[%dttr p=hoon q=hoon]
177+```
120178
121−##### Produces
179+#### Produces
122180
123181Nock of formula `q` and subject `p`, with type `%noun`.
124182
125−##### Syntax
183+#### Regular syntax
126184
127−Regular: **2-fixed**.
185+Two arguments, fixed.
128186
129−##### Discussion
187+Tall-form:
188+
189+```hoon
190+.* p
191+q
192+```
193+
194+Wide-form:
195+
196+```hoon
197+.*(p q)
198+```
199+
200+#### Discussion
130201
131202`.*(p q)` is used to run Nock formula `q` on the subject `p` from within Hoon.
132203
@@ -135,7 +206,7 @@ Keep in mind that `p` and `q` can be arbitrary Hoon expressions, as long as they
135206Note also that `.*` ("dottar") can be used to bypass the type system. It's
136207therefore possible to use Hoon as a typeless language.
137208
138−##### Examples
209+#### Examples
139210
140211```
141212> .*([20 30] [0 2])
@@ -157,32 +228,52 @@ therefore possible to use Hoon as a typeless language.
1572281
158229```
159230
160−### `.=` "dottis" {#dottis}
231+## `.=` "dottis" {#dottis}
232+
233+Test for equality with Nock `5`.
234+
235+#### AST
161236
162−`[%dtts p=hoon q=hoon]`: test for equality with Nock `5`.
237+```hoon
238+[%dtts p=hoon q=hoon]
239+```
163240
164−##### Produces
241+#### Produces
165242
166243`%.y` if `p` equals `q`; otherwise `%.n`.
167244
168−##### Syntax
245+#### Regular syntax
246+
247+Two arguments, fixed.
248+
249+Tall-form:
250+
251+```hoon
252+.= p
253+q
254+```
169255
170−Regular: **2-fixed**.
256+Wide-form:
171257
172−Irregular: `=(a b)` is `.=(a b)`.
258+```hoon
259+.=(p q)
260+```
173261
174−##### Discussion
262+#### Irregular syntax
175263
176−The test for equality includes a type check. Either the type of `p` must nest under the type of `q`, or _vice versa_. Otherwise the result is a crash.
264+```hoon
265+=(p q)
266+```
267+
268+#### Discussion
177269
178270Like Nock equality, `.=` ("dottis") tests whether two nouns are the same,
179−ignoring invisible pointer structure. Because in a conventional
180−noun implementation each noun has a lazy short hash, comparisons
181−are fast unless the hash needs to be computed, or we are comparing
182−separate copies of identical nouns. (Comparing large duplicates
183−is a common cause of performance bugs.)
271+ignoring invisible pointer structure. Because in a conventional noun
272+implementation each noun has a lazy short hash, comparisons are fast unless the
273+hash needs to be computed, or we are comparing separate copies of identical
274+nouns. (Comparing large duplicates is a common cause of performance bugs.)
184275
185−##### Examples
276+#### Examples
186277
187278```
188279> .=(0 0)
@@ -198,22 +289,44 @@ is a common cause of performance bugs.)
198289%.n
199290
200291> =(12 [12 14])
201−nest-fail
292+%.n
202293```
203294
204−### `.?` "dotwut"
295+## `.?` "dotwut"
296+
297+Test for cell or atom with Nock `3`.
205298
206−`[%dtwt p=hoon]`: test for cell or atom with Nock `3`.
299+#### AST
300+
301+```hoon
302+[%dtwt p=hoon]
303+```
207304
208−##### Produces
305+#### Produces
209306
210307`%.y` if `p` is a cell; otherwise `%.n`.
211308
212−##### Syntax
309+#### Regular syntax
310+
311+One argument, fixed.
312+
313+Tall-form:
314+
315+```hoon
316+.? p
317+```
318+
319+Wide-form:
320+
321+```hoon
322+.?(p)
323+```
324+
325+#### Irregular syntax
213326
214−Regular: **1-fixed**.
327+None.
215328
216−##### Examples
329+#### Examples
217330
218331```
219332> .?(42)