git.iko.soy/urbit.org
on d452c09 help sign in
urbit.org/docs/programming/reference/library/3g.md
334 lines 6.5 kB history raw
1# 3g: molds and mold builders
2### `++coin`
4Noun literal syntax cases
6Noun literal syntax cases: atoms, jammed nouns, and nestable tuples.
7Parsed and printed using `++so` and `++co` cores.
9Source
10------
12 ++ coin $% {$$ p/dime} ::
13 {$blob p/*} ::
14 {$many p/(list coin)} ::
15 == ::
17Examples
18--------
20 > `coin`(need (slay '~s1'))
21 [%$ p=[p=~.dr q=18.446.744.073.709.551.616]]
22 > `coin`(need (slay '0x2b59'))
23 [%$ p=[p=~.ux q=11.097]]
25 > ~(rend co [%many ~[[%$ %ud 1] [%$ %tas 'a'] [%$ %s -2]]])
26 "._1_a_-2__"
27 > ._1_a_-2__
28 [1 %a -2]
30 > `@uv`(jam [3 4])
31 0v2cd1
32 > (slay '~02cd1')
33 [~ [%blob p=[3 4]]]
34 > ~02cd1
35 [3 4]
39***
40### `++dime`
42Odor-atom pair
44Used in `++coin`. Convenience methods `++scot` and `++scow` (in
45Section 2eL) print dimes as `++cord` and `++tape`, respectively.
46`++slat`, `++slav`, and `++slaw` are used to parse atoms of
47specific odors.
49Source
50------
52 ++ dime {p/@ta q/@} ::
55Examples
56--------
58 > +>:(slay '0x123')
59 p=[p=~.ux q=291]
63***
64### `++edge`
66Parsing location metadata
68Optional result `p` and parsing continuation `q`.
70Source
71------
73 ++ hair {p/@ud q/@ud} :: parsing trace
76Examples
77--------
79See also: Section 2eD, `++rule`
81 > *edge
82 [p=[p=0 q=0] q=~]
83 > (tall:vast [1 1] "a b")
84 [p=[p=1 q=2] q=[~ [p=[%cnzz p=~[%a]] q=[p=[p=1 q=2] q=" b"]]]]
88***
89### `++hair`
91Parsing line and column
93A pair of two [`@ud`]() used in parsing indicating line and column number.
95Source
96------
98 ++ hair {p/@ud q/@ud} :: parsing trace
101Examples
102--------
104 > *hair
105 [p=0 q=0]
107 > `hair`[1 1] :: parsing starts at [1 1] as a convention.
108 [p=1 q=1]
109 > ((plus ace) [1 1] " --")
110 [p=[p=1 q=4] q=[~ u=[p=[~~. " "] q=[p=[p=1 q=4] q="--"]]]]
111 > `hair`p:((plus ace) [1 1] " --")
112 [p=1 q=4]
116***
117### `++like`
119Mold generator for an edge
121`++like` generates an `++edge` with a parsed result set to a specific type.
123Source
124------
126 ++ like |* a/$-(* *) :: generic edge
127 |= b/_`*`[(hair) ~] ::
128 :- p=(hair -.b) ::
129 ^= q ::
130 ?@ +.b ~ ::
131 :- ~ ::
132 u=[p=(a +>-.b) q=[p=(hair -.b) q=(tape +.b)]] ::
135Examples
136--------
137 > *(like char)
138 [p=[p=0 q=0] q=~]
140 > (ace [1 1] " a")
141 [p=[p=1 q=2] q=[~ [p=~~. q=[p=[p=1 q=2] q="a"]]]]
142 > `(like char)`(ace [1 1] " a")
143 [p=[p=1 q=2] q=[~ [p=~~. q=[p=[p=1 q=2] q="a"]]]]
144 > `(like ,@)`(ace [1 1] " a")
145 [p=[p=1 q=2] q=[~ [p=32 q=[p=[p=1 q=2] q="a"]]]]
149***
150### `++nail`
152Location, remainder of parsed text
154Indicates parsing position `p`, and remaining text to be parsed `q`.
156Source
157------
159 ++ nail {p/hair q/tape} :: parsing input
162Examples
163--------
165 > +<:;~(plug cab cab)
166 c=tub=[p=[p=0 q=0] q=""]
167 > :: tub is a ++nail
171***
172### `++path`
174Filesystem path
176A `++path` is a list of `++span`s aka `@ta`. Used in
177`%clay` and `%eyre` extensively.
179Source
180------
182 ++ path (list knot) :: filesys location
185Examples
186--------
188 > `path`"abc"
189 /a/b/c
193***
194### `++pint`
196Parsing range
198Mostly used for stacktraces. A `++pint` is a pair of
199`++hair`, indicating from `p` to `q`.
201Source
202------
204 ++ pint {p/{p/@ q/@} q/{p/@ q/@}} :: line+column range
207Examples
208--------
210 > !:(!!)
211 ! /~zod/try/~2014.9.20..01.22.04..52e3/:<[1 4].[1 6]>
212 > :: !! always produces a crash
213 > `pint`[[1 4] [1 6]]
214 [p=[p=1 q=4] q=[p=1 q=6]]
218***
219### `++rule`
221Parsing rule
223`++rule` is an empty parsing rule, but it is used to check
224that parsing rules match this with `_`.
227Source
228------
230 ++ rule _|=(nail *edge) :: parsing rule
233Examples
234--------
236 > *rule
237 [p=[p=0 q=0] q=[~ [p=0 q=[p=[p=0 q=0] q=""]]]]
239 > ^+(rule [|=(a=nail [p.a ~])]:|6)
240 <1.dww [tub=[p=[p=@ud q=@ud] q=""] <101.jzo 1.ypj %164>]>
241 > (^+(rule [|=(a=nail [p.a ~ u=['a' a]])]:|6) [1 1] "hi")
242 [p=[p=1 q=1] q=[~ [p=97 q=[p=[p=1 q=1] q="hi"]]]]
243 > ([|=(a=nail [p.a ~ u=['a' a]])]:|6 [1 1] "hi")
244 [[p=1 q=1] ~ u=['a' p=[p=1 q=1] q="hi"]]
248***
249### `++spot`
251Stack trace line
253A `++spot` is what we print after crashing.
255Source
256------
258 ++ spot {p/path q/pint} :: range in file
261Examples
262--------
264 > :into /=main=/bin/fail/hoon '!: !!'
265 + /~zod/main/359/bin/fail/hoon
266 > :fail
267 ! /~zod/main/~2014.9.22..18.40.56..ef04/bin/fail/:<[1 5].[1 7]>
268 ! exit
272***
273### `++toon`
275Nock computation result
277Either success (`%0`), a block with list of requests blocked on (`%1`), or
278failure with stack trace (`%2`).
280Source
281------
283 ++ toon $% {$0 p/*} :: success
284 {$1 p/(list)} :: blocks
285 {$2 p/(list tank)} :: stack trace
286 == ::
289Examples
290--------
291 > (mock [[20 21] 0 3] $~)
292 [%0 p=21]
293 > (mock [[0] !=(.^(cy//=main/1))] ,~)
294 [%1 p=~[[31.075 1.685.027.454 1.852.399.981 49 0]]]
295 > (path [31.075 1.685.027.454 1.852.399.981 49 0])
296 /cy/~zod/main/1
298 > (mock [[1 2] !=(!:(+(.)))] ,~)
299 [%2 p=~[[%leaf p="/~zod/try/~2014.9.23..18.34.32..d3c5/:<[1 20].[1 24]>"]]]
303***
304### `++wonk`
306XX Not a model?
308Pull result out of a `++edge`, or crash if there's no result.
310Source
311------
313 ++ wonk |*(veq=edge ?~(q.veq !! p.u.q.veq)) ::
315Examples
316--------
318See also: [`++edge`]()
320 > (wide:vast [1 1] "(add 2 2)")
321 [ p=[p=1 q=10]
322 q
323 [ ~
324 [ p=[%cnhp p=[%cnzz p=~[%add]] q=~[[%dtzy p=%ud q=2] [%dtzy p=%ud q=2]]]
325 q=[p=[p=1 q=10] q=""]
326 ]
327 ]
328 ]
329 > (wonk (wide:vast [1 1] "(add 2 2)"))
330 [%cnhp p=[%cnzz p=~[%add]] q=~[[%dtzy p=%ud q=2] [%dtzy p=%ud q=2]]]
334***