git.iko.soy/urbit.org
on 6d45ede help sign in
urbit.org/docs/hoon/library/3g.md
339 lines 6.5 kB history raw
1---
2navhome: /docs
3---
6# 3g: molds and mold builders
7### `++coin`
9Noun literal syntax cases
11Noun literal syntax cases: atoms, jammed nouns, and nestable tuples.
12Parsed and printed using `++so` and `++co` cores.
14Source
15------
17 ++ coin $% {$$ p/dime} ::
18 {$blob p/*} ::
19 {$many p/(list coin)} ::
20 == ::
22Examples
23--------
25 > `coin`(need (slay '~s1'))
26 [%$ p=[p=~.dr q=18.446.744.073.709.551.616]]
27 > `coin`(need (slay '0x2b59'))
28 [%$ p=[p=~.ux q=11.097]]
30 > ~(rend co [%many ~[[%$ %ud 1] [%$ %tas 'a'] [%$ %s -2]]])
31 "._1_a_-2__"
32 > ._1_a_-2__
33 [1 %a -2]
35 > `@uv`(jam [3 4])
36 0v2cd1
37 > (slay '~02cd1')
38 [~ [%blob p=[3 4]]]
39 > ~02cd1
40 [3 4]
44***
45### `++dime`
47Odor-atom pair
49Used in `++coin`. Convenience methods `++scot` and `++scow` (in
50Section 2eL) print dimes as `++cord` and `++tape`, respectively.
51`++slat`, `++slav`, and `++slaw` are used to parse atoms of
52specific odors.
54Source
55------
57 ++ dime {p/@ta q/@} ::
60Examples
61--------
63 > +>:(slay '0x123')
64 p=[p=~.ux q=291]
68***
69### `++edge`
71Parsing location metadata
73Optional result `p` and parsing continuation `q`.
75Source
76------
78 ++ hair {p/@ud q/@ud} :: parsing trace
81Examples
82--------
84See also: Section 2eD, `++rule`
86 > *edge
87 [p=[p=0 q=0] q=~]
88 > (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"]]]]
93***
94### `++hair`
96Parsing line and column
98A pair of two [`@ud`]() used in parsing indicating line and column number.
100Source
101------
103 ++ hair {p/@ud q/@ud} :: parsing trace
106Examples
107--------
109 > *hair
110 [p=0 q=0]
112 > `hair`[1 1] :: parsing starts at [1 1] as a convention.
113 [p=1 q=1]
114 > ((plus ace) [1 1] " --")
115 [p=[p=1 q=4] q=[~ u=[p=[~~. " "] q=[p=[p=1 q=4] q="--"]]]]
116 > `hair`p:((plus ace) [1 1] " --")
117 [p=1 q=4]
121***
122### `++like`
124Mold generator for an edge
126`++like` generates an `++edge` with a parsed result set to a specific type.
128Source
129------
131 ++ like |* a/$-(* *) :: 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)]] ::
140Examples
141--------
142 > *(like char)
143 [p=[p=0 q=0] q=~]
145 > (ace [1 1] " a")
146 [p=[p=1 q=2] q=[~ [p=~~. q=[p=[p=1 q=2] q="a"]]]]
147 > `(like char)`(ace [1 1] " a")
148 [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"]]]]
154***
155### `++nail`
157Location, remainder of parsed text
159Indicates parsing position `p`, and remaining text to be parsed `q`.
161Source
162------
164 ++ nail {p/hair q/tape} :: parsing input
167Examples
168--------
170 > +<:;~(plug cab cab)
171 c=tub=[p=[p=0 q=0] q=""]
172 > :: tub is a ++nail
176***
177### `++path`
179Filesystem path
181A `++path` is a list of `++span`s aka `@ta`. Used in
182`%clay` and `%eyre` extensively.
184Source
185------
187 ++ path (list knot) :: filesys location
190Examples
191--------
193 > `path`"abc"
194 /a/b/c
198***
199### `++pint`
201Parsing range
203Mostly used for stacktraces. A `++pint` is a pair of
204`++hair`, indicating from `p` to `q`.
206Source
207------
209 ++ pint {p/{p/@ q/@} q/{p/@ q/@}} :: line+column range
212Examples
213--------
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]]
219 [p=[p=1 q=4] q=[p=1 q=6]]
223***
224### `++rule`
226Parsing rule
228`++rule` is an empty parsing rule, but it is used to check
229that parsing rules match this with `_`.
232Source
233------
235 ++ rule _|=(nail *edge) :: parsing rule
238Examples
239--------
241 > *rule
242 [p=[p=0 q=0] q=[~ [p=0 q=[p=[p=0 q=0] q=""]]]]
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")
249 [[p=1 q=1] ~ u=['a' p=[p=1 q=1] q="hi"]]
253***
254### `++spot`
256Stack trace line
258A `++spot` is what we print after crashing.
260Source
261------
263 ++ spot {p/path q/pint} :: range in file
266Examples
267--------
269 > :into /=main=/bin/fail/hoon '!: !!'
270 + /~zod/main/359/bin/fail/hoon
271 > :fail
272 ! /~zod/main/~2014.9.22..18.40.56..ef04/bin/fail/:<[1 5].[1 7]>
273 ! exit
277***
278### `++toon`
280Nock computation result
282Either success (`%0`), a block with list of requests blocked on (`%1`), or
283failure with stack trace (`%2`).
285Source
286------
288 ++ toon $% {$0 p/*} :: success
289 {$1 p/(list)} :: blocks
290 {$2 p/(list tank)} :: stack trace
291 == ::
294Examples
295--------
296 > (mock [[20 21] 0 3] $~)
297 [%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
303 > (mock [[1 2] !=(!:(+(.)))] ,~)
304 [%2 p=~[[%leaf p="/~zod/try/~2014.9.23..18.34.32..d3c5/:<[1 20].[1 24]>"]]]
308***
309### `++wonk`
311XX Not a model?
313Pull result out of a `++edge`, or crash if there's no result.
315Source
316------
318 ++ wonk |*(veq=edge ?~(q.veq !! p.u.q.veq)) ::
320Examples
321--------
323See also: [`++edge`]()
325 > (wide:vast [1 1] "(add 2 2)")
326 [ p=[p=1 q=10]
327 q
328 [ ~
329 [ p=[%cnhp p=[%cnzz p=~[%add]] q=~[[%dtzy p=%ud q=2] [%dtzy p=%ud q=2]]]
330 q=[p=[p=1 q=10] q=""]
331 ]
332 ]
333 ]
334 > (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]]]
339***