git.iko.soy/urbit.org
on c19b089 help sign in
urbit.org/hoon/reference/stdlib/4e.md
471 lines 8.3 kB history raw
1+++
2title = "4e: Parsing (Combinators)"
3weight = 32
4template = "doc.html"
5+++
7### `++bend`
9Conditional composer
11Parsing composer: connects the `++edge` `vex` with the subsequent `++rule` `sab`
12as an optional suffix, using gate `raq` to compose or reject its
13result. If there is no suffix, or if the suffix fails to be composed
14with the current result, the current result is produced. Used to map a
15group of rules to a specified output.
17#### Accepts
19`raq` is a gate.
21`sab` is a rule.
23`vex` is an edge.
25#### Produces
27A `++rule`.
29#### Source
31```hoon
32 ++ bend :: conditional comp
33 ~/ %bend
34 |* raq/_|*({a/* b/*} [~ u=[a b]])
35 ~/ %fun
36 |* {vex/edge sab/rule}
37 ?~ q.vex
38 vex
39 =+ yit=(sab q.u.q.vex)
40 =+ yur=(last p.vex p.yit)
41 ?~ q.yit
42 [p=yur q=q.vex]
43 =+ vux=(raq p.u.q.vex p.u.q.yit)
44 ?~ vux
45 [p=yur q=q.vex]
46 [p=yur q=[~ u=[p=u.vux q=q.u.q.yit]]]
47 ::
48```
50#### Examples
52```
53 > (;~((bend |=([a/char b/char] ?.(=(a b) ~ (some +(a))))) prn prn) [1 1] "qs")
54 [p=[p=1 q=3] q=[~ u=[p=~~q q=[p=[p=1 q=2] q="s"]]]]
56 > (;~((bend |=([a/char b/char] ?.(=(a b) ~ (some +(a))))) prn prn) [1 1] "qqq")
57 [p=[p=1 q=3] q=[~ u=[p=~~r q=[p=[p=1 q=3] q="q"]]]]
59 > (scan "aa" ;~((bend |=([a/char b/char] ?.(=(a b) ~ (some +(a))))) prn prn))
60 ~~b
62 > (scan "ba" ;~((bend |=([a/char b/char] ?.(=(a b) ~ (some +(a))))) prn prn))
63 ! {1 3}
64 ! exit
66 > `(unit @tas)`(scan "" ;~((bend) (easy ~) sym))
67 ~
69 > `(unit @tas)`(scan "sep" ;~((bend) (easy ~) sym))
70 [~ %sep]
71```
74---
75### `++comp`
77Arbitrary compose
79Parsing composer: connects the `++edge` `vex` with a following `++rule` `sab`,
80combining the contents of `vex` with the result of `sab` using a binary
81gate `raq`. Used to fold over the results of several `++rules`.
83#### Accepts
85`raq` is a gate that accepts a cell of two nouns, `a` and `b`, and
86produces a cell of two nouns.
88`sab` is a rule.
90`vex` is an edge.
92#### Produces
94A `++rule`.
96#### Source
98```hoon
99 ++ comp
100 ~/ %comp
101 |* raq/_|*({a/* b/*} [a b]) :: arbitrary compose
102 ~/ %fun
103 |* {vex/edge sab/rule}
104 ~! +<
105 ?~ q.vex
106 vex
107 =+ yit=(sab q.u.q.vex)
108 =+ yur=(last p.vex p.yit)
109 ?~ q.yit
110 [p=yur q=q.yit]
111 [p=yur q=[~ u=[p=(raq p.u.q.vex p.u.q.yit) q=q.u.q.yit]]]
112 ::
113```
115#### Examples
117```
118 > (scan "123" ;~((comp |=([a/@u b/@u] (add a b))) dit dit dit))
119 6
120 > (scan "12" ;~((comp |=([a/@u b/@u] (add a b))) dit dit dit))
121 ! {1 3}
122 ! exit
123```
125---
126### `++fail`
128Never parse
130Produces an `++edge` at the same text position (`++hair`) with a failing
131result (`q=~`).
133#### Accepts
135`tub` is a `++nail`.
137#### Produces
139An `++edge`.
141#### Source
143```hoon
144 ++ fail |=(tub/nail [p=p.tub q=~]) :: never parse
145```
147#### Examples
149```
150 > (fail [[1 1] "abc"])
151 [p=[p=1 q=1] q=~]
153 > (fail [[p=1.337 q=70] "Parse me, please?"])
154 [p=[p=1.337 q=70] q=~]
155```
158---
159### `++glue`
161Skip delimiter
163Parsing composer: connects an `++edge` `vex` with a following `++rule` `sab` by
164parsing the `++rule` `bus` (the delimiting symbol) and throwing out the
165result.
167#### Accepts
169`bus` is a `++rule`.
171`sab` is a `++rule`.
173`vex` is an `++edge`.
175#### Produces
179#### Source
181```hoon
182 ++ glue :: add rule
183 ~/ %glue
184 |* bus/rule
185 ~/ %fun
186 |* {vex/edge sab/rule}
187 (plug vex ;~(pfix bus sab))
188 ::
189```
191#### Examples
193```
194 > (scan "200|mal|bon" ;~((glue bar) dem sym sym))
195 [q=200 7.102.829 7.237.474]
197 > `[@u @tas @tas]`(scan "200|mal|bon" ;~((glue bar) dem sym sym))
198 [200 %mal %bon]
200 > (scan "200|;|bon" ;~((glue bar) dem sem sym))
201 [q=200 ~~~3b. 7.237.474]
203 > (scan "200.;.bon" ;~((glue dot) dem sem sym))
204 [q=200 ~~~3b. 7.237.474]
205```
207---
208### `++less`
210Parse unless
212Parsing composer: if an `++edge` `vex` reflects a success, fail. Otherwise,
213connect `vex` with the following `++rule`.
215#### Accepts
217`sab` is a `++rule`.
219`vex` is an `++edge`.
221#### Produces
225#### Source
227```hoon
228 ++ less :: no first and second
229 |* {vex/edge sab/rule}
230 ?~ q.vex
231 =+ roq=(sab)
232 [p=(last p.vex p.roq) q=q.roq]
233 (fail +<.sab)
234 ::
235```
237#### Examples
239```
240 > (scan "sas-/lo" (star ;~(less lus bar prn)))
241 "sas-/lo"
243 > (scan "sas-/l+o" (star ;~(less lus bar prn)))
244 ! {1 8}
245 ! exit
247 > (scan "sas|-/lo" (star ;~(less lus bar prn)))
248 ! {1 5}
249 ! exit
250```
253---
254### `++pfix`
256Discard first rule
258Parsing composer: connects an `++edge` `vex` with two subsequent `++rule`s,
259ignoring the result of the first and producing the result of the second.
261#### Accepts
263`vex` is an edge.
265#### Produces
269#### Source
271```hoon
272 ++ pfix :: discard first rule
273 ~/ %pfix
274 (comp |*({a/* b/*} b))
275```
277#### Examples
279```
280 > `@t`(scan "%him" ;~(pfix cen sym))
281 'him'
283 > (scan "+++10" ;~(pfix (star lus) dem))
284 q=10
285```
288---
289### `++plug`
291Parse to tuple
293Parsing composer: connects an `++edge` `vex` with a following `++rule` `sab`, producing
294a cell of both the results. See also: the monad applicator ;\~ for a
295more detailed explanation.
297#### Accepts
299`sab` is a `++rule`.
301`vex` is an `++edge`.
303#### Produces
307#### Source
309```hoon
310 ++ plug :: first then second
311 ~/ %plug
312 |* {vex/edge sab/rule}
313 ?~ q.vex
314 vex
315 =+ yit=(sab q.u.q.vex)
316 =+ yur=(last p.vex p.yit)
317 ?~ q.yit
318 [p=yur q=q.yit]
319 [p=yur q=[~ u=[p=[p.u.q.vex p.u.q.yit] q=q.u.q.yit]]]
320 ::
321```
323#### Examples
325```
326 > (scan "1..20" ;~(plug dem dot dot dem))
327 [q=1 ~~~. ~~~. q=20]
329 > (scan "moke/~2014.1.1" ;~(plug sym fas nuck:so))
330 [1.701.539.693 ~~~2f. [% p=[p=~.da q=170.141.184.500.766.106.671.844.917.172.921.958.400]]]
332 > ;;(,[@tas @t ~ %da @da] (scan "moke/~2014.1.1" ;~(plug sym fas nuck:so)))
333 [%moke '/' ~ %da ~2014.1.1]
334```
337---
338### `++pose`
340Parse options
342Parsing composer: if `vex` reflects a failure, connect it with the
343following rule `sab`. See also: the monad applicator ;\~
345#### Accepts
347`sab` is a `++rule`.
349`vex` is an `++edge`.
351#### Produces
355#### Source
357```hoon
358 ++ pose :: first or second
359 ~/ %pose
360 |* {vex/edge sab/rule}
361 ?~ q.vex
362 =+ roq=(sab)
363 [p=(last p.vex p.roq) q=q.roq]
364 vex
365 ::
366```
368#### Examples
370```
371 > `@t`(scan "+" ;~(pose lus tar cen))
372 '+'
374 > `@t`(scan "*" ;~(pose lus tar cen))
375 '*'
377 > `@t`(scan "%" ;~(pose lus tar cen))
378 '%'
380 > `@t`(scan "-" ;~(pose lus tar cen))
381 ! {1 1}
382 ! exit
383```
386---
387### `++sfix`
389Discard second rule
391Parsing composer: connects `++edge`s `vex` with two subsequent `++rule`s returning the
392result of the first and discarding the result of the second.
394#### Accepts
396`a` is the result of parsing the first `++rule`.
398`b` is the result of of parsing the second `++rule`.
400#### Produces
404#### Source
406```hoon
407 ++ sfix :: discard second rule
408 ~/ %sfix
409 (comp |*({a/* b/*} a))
410```
412#### Examples
414```
415 > `@t`(scan "him%" ;~(sfix sym cen))
416 'him'
418 > (scan "10+++" ;~(sfix dem (star lus)))
419 q=10
420```
423---
424### `++simu`
426First and second
428Parsing composer: if an `++edge` `vex` reflects a failure, fail. Otherwise,
429connect `vex` with the following `++rule`.
431#### Accepts
433`sab` is a `++rule`.
435`vex` is an `++edge`.
437#### Produces
441#### Source
443```hoon
444 ++ simu :: first and second
445 |* {vex/edge sab/rule}
446 ?~ q.vex
447 vex
448 =+ roq=(sab)
449 roq
450 ::
451```
453#### Examples
455```
456 > (scan "~zod" scat:vast)
457 [%dtzy p=%p q=0]
459 > (scan "%zod" scat:vast)
460 [%dtzz p=%tas q=6.582.138]
462 > (scan "%zod" ;~(simu cen scat:vast))
463 [%dtzz p=%tas q=6.582.138]
465 > (scan "~zod" ;~(simu cen scat:vast))
466 ! {1 1}
467 ! exit
468```
471---