git.iko.soy/urbit.org
on master help sign in
Update 3g
52e2d2brmariani
docs/hoon/library/3g.md+145−133
compare with master
unifiedsplit
@@ -6,24 +6,25 @@ navhome: /docs/
6# 3g: molds and mold builders
6# 3g: molds and mold builders
7### `++coin`
7### `++coin`
8
8
9−Noun literal syntax cases
10
9
11−Noun literal syntax cases: atoms, jammed nouns, and nestable tuples.
10+Noun-literal syntax cases
12−Parsed and printed using `++so` and `++co` cores.
13
11
14−Source
12+Syntax cases for nouns-literal: atoms, jammed nouns, and nestable tuples. Parsed
15−------
13+and printed using `++so` and `++co` cores.
16
14
17− ++ coin $% {$$ p/dime} ::
15+#### Source
18− {$blob p/*} ::
19− {$many p/(list coin)} ::
20− == ::
21
16
17+ ++ coin $% [$$ p=dime]
18+ [$blob p=*]
19+ [$many p=(list coin)]
20+ ==
21+
22+***
22−Examples
23+#### Examples
23−--------
24
24
25 > `coin`(need (slay '~s1'))
25 > `coin`(need (slay '~s1'))
26 [%$ p=[p=~.dr q=18.446.744.073.709.551.616]]
26 [%$ p=[p=~.dr q=18.446.744.073.709.551.616]]
27+
27 > `coin`(need (slay '0x2b59'))
28 > `coin`(need (slay '0x2b59'))
28 [%$ p=[p=~.ux q=11.097]]
29 [%$ p=[p=~.ux q=11.097]]
29
30
@@ -34,8 +35,10 @@ Examples
34
35
35 > `@uv`(jam [3 4])
36 > `@uv`(jam [3 4])
36 0v2cd1
37 0v2cd1
38+
37 > (slay '~02cd1')
39 > (slay '~02cd1')
38 [~ [%blob p=[3 4]]]
40 [~ [%blob p=[3 4]]]
41+
39 > ~02cd1
42 > ~02cd1
40 [3 4]
43 [3 4]
41
44
@@ -44,27 +47,22 @@ Examples
44***
47***
45### `++dime`
48### `++dime`
46
49
47−Odor-atom pair
50+Aura-atom pair
48−
49−Used in `++coin`. Convenience methods `++scot` and `++scow` (in
50−Section 2eL) print dimes as `++cord` and `++tape`, respectively.
51−`++slat`, `++slav`, and `++slaw` are used to parse atoms of
52−specific odors.
53
51
54−Source
52+Used in `++coin`. Convenience methods [`++scot`](../4m.md) and
55−------
53+[`++scow`](../4m.md) print dimes as `++cord` and `++tape`, respectively.
54+[`++slat`](../4m.md), [`++slav`](../4m.md), and [`++slaw`](../4m.md) are used
55+to parse atoms of specific auras.
56
56
57− ++ dime {p/@ta q/@} ::
57+#### Source
58
58
59+ ++ dime [p=@ta q=@]
59
60
60−Examples
61+#### Examples
61−--------
62
62
63 > +>:(slay '0x123')
63 > +>:(slay '0x123')
64 p=[p=~.ux q=291]
64 p=[p=~.ux q=291]
65
65
66−
67−
68***
66***
69### `++edge`
67### `++edge`
70
68
@@ -72,22 +70,23 @@ Parsing location metadata
72
70
73Optional result `p` and parsing continuation `q`.
71Optional result `p` and parsing continuation `q`.
74
72
75−Source
73+#### Source
76−------
77
74
78− ++ hair {p/@ud q/@ud} :: parsing trace
75+ ++ hair [p=@ud q=@ud]
79
76
80
77
81−Examples
78+#### Examples
82−--------
83
79
84−See also: Section 2eD, `++rule`
85
80
86 > *edge
81 > *edge
87 [p=[p=0 q=0] q=~]
82 [p=[p=0 q=0] q=~]
83+
88 > (tall:vast [1 1] "a b")
84 > (tall:vast [1 1] "a b")
89− [p=[p=1 q=2] q=[~ [p=[%cnzz p=~[%a]] q=[p=[p=1 q=2] q=" b"]]]]
85+ [p=[p=1 q=3] q=[~ u=[p=[%wing p=~[%a]] q=[p=[p=1 q=2] q=" b"]]]]
90
86
87+#### Discussion
88+
89+See also: [Section 2e](../2e.md), `++rule`
91
90
92
91
93***
92***
@@ -95,60 +94,58 @@ See also: Section 2eD, `++rule`
95
94
96Parsing line and column
95Parsing line and column
97
96
98−A pair of two [`@ud`]() used in parsing indicating line and column number.
97+A pair of two `@ud` used in parsing indicating line and column number.
99
98
100−Source
99+#### Source
101−------
102
100
103− ++ hair {p/@ud q/@ud} :: parsing trace
101+ ++ hair [p=@ud q=@ud]
104
102
105
103
106−Examples
104+#### Examples
107−--------
108
105
109 > *hair
106 > *hair
110 [p=0 q=0]
107 [p=0 q=0]
111
108
112− > `hair`[1 1] :: parsing starts at [1 1] as a convention.
109+ > `hair`[1 1] :: parsing starts at [1 1] as a convention.
113 [p=1 q=1]
110 [p=1 q=1]
111+
114 > ((plus ace) [1 1] " --")
112 > ((plus ace) [1 1] " --")
115 [p=[p=1 q=4] q=[~ u=[p=[~~. " "] q=[p=[p=1 q=4] q="--"]]]]
113 [p=[p=1 q=4] q=[~ u=[p=[~~. " "] q=[p=[p=1 q=4] q="--"]]]]
114+
116 > `hair`p:((plus ace) [1 1] " --")
115 > `hair`p:((plus ace) [1 1] " --")
117 [p=1 q=4]
116 [p=1 q=4]
118
117
119
118
120−
121***
119***
122### `++like`
120### `++like`
123
121
124−Mold generator for an edge
122+Generic edge
123+
124+Generates an `++edge` with a parsed result set to a specific type.
125
125
126−`++like` generates an `++edge` with a parsed result set to a specific type.
126+#### Source
127
127
128−Source
128+ ++ like |* a=gate
129−------
129+ |= b=_`*`[(hair) ~]
130+ :- p=(hair -.b)
131+ ^= q
132+ :- ~
133+ u=[p=(a +>-.b) q=[p=(hair -.b) q=(tape +.b)]]
130
134
131− ++ like |* a/gate :: generic edge
132− |= b/_`*`[(hair) ~] ::
133− :- p=(hair -.b) ::
134− ^= q ::
135− ?@ +.b ~ ::
136− :- ~ ::
137− u=[p=(a +>-.b) q=[p=(hair -.b) q=(tape +.b)]] ::
138
135
136+#### Examples
139
137
140−Examples
141−--------
142 > *(like char)
138 > *(like char)
143 [p=[p=0 q=0] q=~]
139 [p=[p=0 q=0] q=~]
144
140
145 > (ace [1 1] " a")
141 > (ace [1 1] " a")
146− [p=[p=1 q=2] q=[~ [p=~~. q=[p=[p=1 q=2] q="a"]]]]
142+ [p=[p=1 q=2] q=[~ u=[p=' ' q=[p=[p=1 q=2] q="a"]]]]
143+
147 > `(like char)`(ace [1 1] " a")
144 > `(like char)`(ace [1 1] " a")
148 [p=[p=1 q=2] q=[~ [p=~~. q=[p=[p=1 q=2] q="a"]]]]
145 [p=[p=1 q=2] q=[~ [p=~~. q=[p=[p=1 q=2] q="a"]]]]
149− > `(like ,@)`(ace [1 1] " a")
150− [p=[p=1 q=2] q=[~ [p=32 q=[p=[p=1 q=2] q="a"]]]]
151
146
147+ > `(like ,@)`(ace [1 1] " a")
148+ [p=[p=1 q=2] q=[~ u=[p=32 q=[p=[p=1 q=2] q="a"]]]]
152
149
153
150
154***
151***
@@ -158,63 +155,55 @@ Location, remainder of parsed text
158
155
159Indicates parsing position `p`, and remaining text to be parsed `q`.
156Indicates parsing position `p`, and remaining text to be parsed `q`.
160
157
161−Source
158+#### Source
162−------
163
159
164− ++ nail {p/hair q/tape} :: parsing input
160+ ++ nail [p=hair q=tape]
165
161
166
162
167−Examples
163+#### Examples
168−--------
169
164
170 > +<:;~(plug cab cab)
165 > +<:;~(plug cab cab)
171− c=tub=[p=[p=0 q=0] q=""]
166+ c=[p=[p=0 q=0] q=""]
172− > :: tub is a ++nail
173−
174−
175
167
176***
168***
177### `++path`
169### `++path`
178
170
179Filesystem path
171Filesystem path
180
172
181−A `++path` is a list of `++span`s aka `@ta`. Used in
173+A list of `++knot`s. `++knot` is another name for `@ta`.
182−`%clay` and `%eyre` extensively.
183
174
184−Source
175+#### Source
185−------
186
176
187− ++ path (list knot) :: filesys location
177+ ++ path (list knot)
188
178
189
179
190−Examples
180+#### Examples
191−--------
192
181
193 > `path`"abc"
182 > `path`"abc"
194 /a/b/c
183 /a/b/c
195
184
185+#### Discussion
196
186
187+Used in `%clay` and `%eyre` extensively.
197
188
198***
189***
199### `++pint`
190### `++pint`
200
191
201Parsing range
192Parsing range
202
193
203−Mostly used for stacktraces. A `++pint` is a pair of
204−`++hair`, indicating from `p` to `q`.
194+A `++pint` is a pair of `++hair`, indicating from `p` to `q`. Mostly used for
195+stack traces.
205
196
206−Source
197+#### Source
207−------
208
198
209− ++ pint {p/{p/@ q/@} q/{p/@ q/@}} :: line+column range
199+ ++ pint [p=[p=@ q=@] q=[p=@ q=@]]
210
200
211
201
212−Examples
202+#### Examples
213−--------
203+
204+ > !:(!!) :: !! always produces a crash
205+ /~zod/home/~2014.9.20..01.22.04..52e3/:<[1 4].[1 6]>
214
206
215− > !:(!!)
216− ! /~zod/try/~2014.9.20..01.22.04..52e3/:<[1 4].[1 6]>
217− > :: !! always produces a crash
218 > `pint`[[1 4] [1 6]]
207 > `pint`[[1 4] [1 6]]
219 [p=[p=1 q=4] q=[p=1 q=6]]
208 [p=[p=1 q=4] q=[p=1 q=6]]
220
209
@@ -225,115 +214,138 @@ Examples
225
214
226Parsing rule
215Parsing rule
227
216
228−`++rule` is an empty parsing rule, but it is used to check
229−that parsing rules match this with `_`.
217+An empty parsing rule, but used to check that parsing rules match this with `_`.
230−
231
218
232−Source
233−------
234
219
235− ++ rule _|=(nail *edge) :: parsing rule
220+#### Source
236
221
222+ ++ rule _|=(nail *edge)
237
223
238−Examples
239−--------
240
224
241− > *rule
225+#### Examples
242− [p=[p=0 q=0] q=[~ [p=0 q=[p=[p=0 q=0] q=""]]]]
243
226
244− > ^+(rule [|=(a=nail [p.a ~])]:|6)
245− <1.dww [tub=[p=[p=@ud q=@ud] q=""] <101.jzo 1.ypj %164>]>
246− > (^+(rule [|=(a=nail [p.a ~ u=['a' a]])]:|6) [1 1] "hi")
247− [p=[p=1 q=1] q=[~ [p=97 q=[p=[p=1 q=1] q="hi"]]]]
248 > ([|=(a=nail [p.a ~ u=['a' a]])]:|6 [1 1] "hi")
227 > ([|=(a=nail [p.a ~ u=['a' a]])]:|6 [1 1] "hi")
249 [[p=1 q=1] ~ u=['a' p=[p=1 q=1] q="hi"]]
228 [[p=1 q=1] ~ u=['a' p=[p=1 q=1] q="hi"]]
250
229
251
230
252−
253***
231***
254### `++spot`
232### `++spot`
255
233
256Stack trace line
234Stack trace line
257
235
258−A `++spot` is what we print after crashing.
236+The stack trace that is printed after crashing.
259−
260−Source
261−------
262
237
263− ++ spot {p/path q/pint} :: range in file
238+#### Source
264
239
240+ ++ spot [p=path q=pint]
265
241
266−Examples
242+#### Examples
267−--------
268
243
269− > :into /=main=/bin/fail/hoon '!: !!'
244+ > !: !! :: !! always produces a crash
270− + /~zod/main/359/bin/fail/hoon
245+ /~zod/home/~2018.8.8..21.42.40..7852:<[1 5].[1 7]>
271− > :fail
272− ! /~zod/main/~2014.9.22..18.40.56..ef04/bin/fail/:<[1 5].[1 7]>
273 ! exit
246 ! exit
274
247
275
248
249+***
250+### `++tone`
251+
252+Nock result, error report
253+
254+Produces either success (`%0`), a block with list of requests blocked on (`%1`),
255+or failure with an error report (`%2`).
256+
257+
258+#### Source
259+
260+ ++ tone $% [$0 p=*] :: success
261+ [$1 p=(list)] :: blocks
262+ [$2 p=(list [@ta *])] :: error report
263+ ==
264+
265+#### Examples
266+
267+ > (mink [[20 21] 0 3] $~)
268+ [%0 p=21]
269+
270+
271+ > (mink [[1 2] !=(!:(+(.)))] ,~)
272+ [ %2
273+ p
274+ ~[
275+ [ ~.spot
276+ [ [ \/72.245.008.048.359.254.300.063.028.130.093.488.830.539.186.242.06\/
277+ 3.318.457.928.725.368.447.417.075.673.617.723.940.025.940.705.343
278+ .057.601.925.133.611.559.292.046.932.324.629.048.702
279+ \/ \/
280+ 1.701.670.760
281+ \/347.698.068.472.453.194.464.038.059.283.550.210.118.689.128.761.6\/
282+ 88.459.326.078
283+ \/ \/
284+ 0
285+ ]
286+ [1 20]
287+ 1
288+ 24
289+ ]
290+ ]
291+ ]
292+
276
293
277***
294***
278### `++toon`
295### `++toon`
279
296
280−Nock computation result
297+Nock result, stack trace
281
298
282−Either success (`%0`), a block with list of requests blocked on (`%1`), or
299+Produces either success (`%0`), a block with list of requests blocked on (`%1`),
283−failure with stack trace (`%2`).
300+or failure with a stack trace (`%2`).
284
301
285−Source
286−------
287
302
288− ++ toon $% {$0 p/*} :: success
303+#### Source
289− {$1 p/(list)} :: blocks
290− {$2 p/(list tank)} :: stack trace
291− == ::
292
304
305+ ++ toon $% [$0 p=*] :: success
306+ [$1 p=(list)] :: blocks
307+ [$2 p=(list tank)] :: stack trace
308+ ==
309+
310+
311+#### Examples
293
312
294−Examples
295−--------
296 > (mock [[20 21] 0 3] $~)
313 > (mock [[20 21] 0 3] $~)
297 [%0 p=21]
314 [%0 p=21]
298− > (mock [[0] !=(.^(cy//=main/1))] ,~)
299− [%1 p=~[[31.075 1.685.027.454 1.852.399.981 49 0]]]
300− > (path [31.075 1.685.027.454 1.852.399.981 49 0])
301− /cy/~zod/main/1
302
315
303 > (mock [[1 2] !=(!:(+(.)))] ,~)
316 > (mock [[1 2] !=(!:(+(.)))] ,~)
304 [%2 p=~[[%leaf p="/~zod/try/~2014.9.23..18.34.32..d3c5/:<[1 20].[1 24]>"]]]
317 [%2 p=~[[%leaf p="/~zod/try/~2014.9.23..18.34.32..d3c5/:<[1 20].[1 24]>"]]]
305
318
306
319
307−
308***
320***
309### `++wonk`
321### `++wonk`
310
322
311−XX Not a model?
323+Product from edge
312
324
313Pull result out of a `++edge`, or crash if there's no result.
325Pull result out of a `++edge`, or crash if there's no result.
314
326
315−Source
327+#### Source
316−------
317
328
318− ++ wonk |*(veq=edge ?~(q.veq !! p.u.q.veq)) ::
329+ ++ wonk |*(veq=edge ?~(q.veq !! p.u.q.veq))
319
330
320−Examples
331+#### Examples
321−--------
322−
323−See also: [`++edge`]()
324
332
325 > (wide:vast [1 1] "(add 2 2)")
333 > (wide:vast [1 1] "(add 2 2)")
326 [ p=[p=1 q=10]
334 [ p=[p=1 q=10]
327 q
335 q
328 [ ~
336 [ ~
337+ u
329− [ p=[%cnhp p=[%cnzz p=~[%add]] q=~[[%dtzy p=%ud q=2] [%dtzy p=%ud q=2]]]
338+ [ p=[%cnhp p=[%wing p=~[%add]] q=~[[%sand p=%ud q=2] [%sand p=%ud q=2]]]
330 q=[p=[p=1 q=10] q=""]
339 q=[p=[p=1 q=10] q=""]
331 ]
340 ]
332 ]
341 ]
333 ]
342 ]
343+
334 > (wonk (wide:vast [1 1] "(add 2 2)"))
344 > (wonk (wide:vast [1 1] "(add 2 2)"))
335− [%cnhp p=[%cnzz p=~[%add]] q=~[[%dtzy p=%ud q=2] [%dtzy p=%ud q=2]]]
345+ [%cnhp p=[%wing p=~[%add]] q=~[[%sand p=%ud q=2] [%sand p=%ud q=2]]]
336
346
347+#### Discussion
337
348
349+See also: `++edge`
338
350
339***
351***