git.iko.soy/urbit.org
on master help sign in
update dot runes
e822ca7Tinnus Napbus
content/docs/hoon/reference/rune/dot.md+172−59
compare with master
unifiedsplit
@@ -7,17 +7,53 @@ aliases = ["docs/reference/hoon-expressions/rune/dot/"]
7
7
8Anything Nock can do, Hoon can do also. These runes are used for carrying out Nock operations in Hoon.
8Anything Nock can do, Hoon can do also. These runes are used for carrying out Nock operations in Hoon.
9
9
10−## Runes
10+## `.^` "dotket"
11
11
12−### `.^` "dotket"
12+Load from the Arvo namespace (scry) with a fake Nock instruction: Nock 12.
13
13
14−`[%dtkt p=spec q=hoon]`: load from the Arvo namespace with a fake Nock instruction: 'Nock `12`''.
14+#### AST
15
15
16+```hoon
17+[%dtkt p=spec q=hoon]
18+```
19+
16−##### Produces
20+#### Produces
17
21
18The noun `q`, cast to the type `p`.
22The noun `q`, cast to the type `p`.
19
23
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+
20−##### Discussion
56+#### Discussion
21
57
22Nock has no `12` instruction! But the virtual Nock
58Nock has no `12` instruction! But the virtual Nock
23used to run userspace code does. Nock `12` loads from a
59used 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
29
65
30In 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.
66In 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.
31
67
32−##### Examples
68+#### Examples
33
69
34In the dojo we can ask Clay -- the Arvo filesystem -- for a listing of the files at our current path, `%`:
70In the dojo we can ask Clay -- the Arvo filesystem -- for a listing of the files at our current path, `%`:
35
71
@@ -37,17 +73,14 @@ In the dojo we can ask Clay -- the Arvo filesystem -- for a listing of the files
37> .^(arch %cy %)
73> .^(arch %cy %)
38[ fil=~
74[ fil=~
39 dir
75 dir
40− { [p=~.web q=~]
41− [p=~.LICENSE q=~]
42− [p=~.app q=~]
76+ { [p=~.app q=~]
43− [p=~.lib q=~]
44− [p=~.sec q=~]
45− [p=~.sys q=~]
46− [p=~.ren q=~]
47 [p=~.sur q=~]
77 [p=~.sur q=~]
48− [p=~.tests q=~]
49− [p=~.mar q=~]
50 [p=~.gen q=~]
78 [p=~.gen q=~]
79+ [p=~.lib q=~]
80+ [p=~.mar q=~]
81+ [p=~.ted q=~]
82+ [p=~.desk q=~]
83+ [p=~.sys q=~]
51 }
84 }
52]
85]
53```
86```
@@ -67,38 +100,57 @@ You can modify the time of the file listing quite simply and ask for a listing f
67> .^(arch %cy /(scot %p our)/base/(scot %da (sub now ~h5)))
100> .^(arch %cy /(scot %p our)/base/(scot %da (sub now ~h5)))
68[ fil=~
101[ fil=~
69 dir
102 dir
70− { [p=~.web q=~]
71− [p=~.LICENSE q=~]
72− [p=~.app q=~]
103+ { [p=~.app q=~]
73− [p=~.lib q=~]
74− [p=~.sec q=~]
75− [p=~.sys q=~]
76− [p=~.ren q=~]
77 [p=~.sur q=~]
104 [p=~.sur q=~]
78− [p=~.tests q=~]
79− [p=~.mar q=~]
80 [p=~.gen q=~]
105 [p=~.gen q=~]
106+ [p=~.lib q=~]
107+ [p=~.mar q=~]
108+ [p=~.ted q=~]
109+ [p=~.desk q=~]
110+ [p=~.sys q=~]
81 }
111 }
82]
112]
83```
113```
84
114
85`our` is the value for your ship's name.
115`our` is the value for your ship's name.
86
116
87−### `.+` "dotlus"
117+## `.+` "dotlus"
88
118
89−`[%dtls p=hoon]`: increment an atom with Nock `4`.
119+Increment an atom with Nock `4`.
90
120
121+#### AST
122+
123+```hoon
124+[%dtls p=hoon]
125+```
126+
91−##### Produces
127+#### Produces
92
128
93`p` plus `1` if `p` is an atom; otherwise, crashes. The product atom has no aura.
129`p` plus `1` if `p` is an atom; otherwise, crashes. The product atom has no aura.
94
130
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+```
96
146
97−Regular: **1-fixed**.
147+#### Irregular syntax
98
148
99−Irregular: `+(6)` is `.+(6)`.
149+```hoon
150++(p)
151+```
100
152
101−##### Examples
153+#### Examples
102
154
103```
155```
104> .+(6)
156> .+(6)
@@ -114,19 +166,38 @@ Irregular: `+(6)` is `.+(6)`.
114nest-fail
166nest-fail
115```
167```
116
168
117−### `.*` "dottar"
169+## `.*` "dottar"
170+
171+Evaluate with Nock `2`.
118
172
173+#### AST
174+
175+```hoon
119−`[%dttr p=hoon q=hoon]`: evaluate with Nock `2`.
176+[%dttr p=hoon q=hoon]
177+```
120
178
121−##### Produces
179+#### Produces
122
180
123Nock of formula `q` and subject `p`, with type `%noun`.
181Nock of formula `q` and subject `p`, with type `%noun`.
124
182
125−##### Syntax
183+#### Regular syntax
126
184
127−Regular: **2-fixed**.
185+Two arguments, fixed.
128
186
187+Tall-form:
188+
189+```hoon
190+.* p
191+q
192+```
193+
194+Wide-form:
195+
196+```hoon
197+.*(p q)
198+```
199+
129−##### Discussion
200+#### Discussion
130
201
131`.*(p q)` is used to run Nock formula `q` on the subject `p` from within Hoon.
202`.*(p q)` is used to run Nock formula `q` on the subject `p` from within Hoon.
132
203
@@ -135,7 +206,7 @@ Keep in mind that `p` and `q` can be arbitrary Hoon expressions, as long as they
135Note also that `.*` ("dottar") can be used to bypass the type system. It's
206Note also that `.*` ("dottar") can be used to bypass the type system. It's
136therefore possible to use Hoon as a typeless language.
207therefore possible to use Hoon as a typeless language.
137
208
138−##### Examples
209+#### Examples
139
210
140```
211```
141> .*([20 30] [0 2])
212> .*([20 30] [0 2])
@@ -157,32 +228,52 @@ therefore possible to use Hoon as a typeless language.
1571
2281
158```
229```
159
230
160−### `.=` "dottis" {#dottis}
231+## `.=` "dottis" {#dottis}
232+
233+Test for equality with Nock `5`.
234+
235+#### AST
161
236
237+```hoon
162−`[%dtts p=hoon q=hoon]`: test for equality with Nock `5`.
238+[%dtts p=hoon q=hoon]
239+```
163
240
164−##### Produces
241+#### Produces
165
242
166`%.y` if `p` equals `q`; otherwise `%.n`.
243`%.y` if `p` equals `q`; otherwise `%.n`.
167
244
168−##### Syntax
245+#### Regular syntax
246+
247+Two arguments, fixed.
248+
249+Tall-form:
250+
251+```hoon
252+.= p
253+q
254+```
169
255
170−Regular: **2-fixed**.
256+Wide-form:
171
257
172−Irregular: `=(a b)` is `.=(a b)`.
258+```hoon
259+.=(p q)
260+```
173
261
174−##### Discussion
262+#### Irregular syntax
175
263
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
177
269
178Like Nock equality, `.=` ("dottis") tests whether two nouns are the same,
270Like Nock equality, `.=` ("dottis") tests whether two nouns are the same,
179−ignoring invisible pointer structure. Because in a conventional
271+ignoring invisible pointer structure. Because in a conventional noun
180−noun implementation each noun has a lazy short hash, comparisons
272+implementation each noun has a lazy short hash, comparisons are fast unless the
181−are fast unless the hash needs to be computed, or we are comparing
273+hash needs to be computed, or we are comparing separate copies of identical
182−separate copies of identical nouns. (Comparing large duplicates
183−is a common cause of performance bugs.)
274+nouns. (Comparing large duplicates is a common cause of performance bugs.)
184
275
185−##### Examples
276+#### Examples
186
277
187```
278```
188> .=(0 0)
279> .=(0 0)
@@ -198,22 +289,44 @@ is a common cause of performance bugs.)
198%.n
289%.n
199
290
200> =(12 [12 14])
291> =(12 [12 14])
201−nest-fail
292+%.n
202```
293```
203
294
204−### `.?` "dotwut"
295+## `.?` "dotwut"
296+
297+Test for cell or atom with Nock `3`.
205
298
299+#### AST
300+
301+```hoon
206−`[%dtwt p=hoon]`: test for cell or atom with Nock `3`.
302+[%dtwt p=hoon]
303+```
207
304
208−##### Produces
305+#### Produces
209
306
210`%.y` if `p` is a cell; otherwise `%.n`.
307`%.y` if `p` is a cell; otherwise `%.n`.
211
308
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
213
326
214−Regular: **1-fixed**.
327+None.
215
328
216−##### Examples
329+#### Examples
217
330
218```
331```
219> .?(42)
332> .?(42)