git.iko.soy/urbit.org
on 514b5fc help sign in
urbit.org/content/docs/hoon/reference/stdlib/4g.md
229 lines 3.8 kB history raw
1+++
2title = "4g: Parsing (Outside Caller)"
3weight = 34
4template = "doc.html"
5+++
7## `++rash`
9Parse or crash
11Parse a cord with a given `rule` and crash if the `cord` isn't entirely
12parsed.
14#### Accepts
16`naf` is an atom.
18`sab` is a `rule`.
20#### Produces
22The value of the parse result, or crash.
24#### Source
26```hoon
27++ rash |*([naf=@ sab=rule] (scan (trip naf) sab))
28```
30#### Examples
32```
33> (rash 'I was the world in which I walked, and what I saw' (star (shim 0 200)))
34"I was the world in which I walked, and what I saw"
36> (rash 'abc' (just 'a'))
37! {1 2}
38! 'syntax-error'
39! exit
41> (rash 'abc' (jest 'abc'))
42'abc'
44> (rash 'abc' (jest 'ab'))
45! {1 3}
46! 'syntax-error'
47! exit
48```
50---
52## `++rose`
54Parse to each
56Parse `tape` `los` with `rule` `sab`, producing an `(each @ud (unit *))`. If
57`los` was not fully consumed, the result is `%.n` and `p` contains the column
58number before failure occurred. If `los` was fully consumed, the result is
59`%.y` and `p` contains either `sab`'s result in a `unit`, or a null `unit` if
60parsing failed.
62#### Accepts
64`los` is a `tape`.
66`sab` is a `rule`.
68#### Produces
70`(each @ud (unit *))`, where the `*` is whatever type the `rule` produces.
72#### Source
74```hoon
75++ rose |* [los=tape sab=rule]
76 =+ vex=(sab [[1 1] los])
77 =+ len=(lent los)
78 ?. =(+(len) q.p.vex) [%| p=(dec q.p.vex)]
79 ?~ q.vex
80 [%& p=~]
81 [%& p=[~ u=p.u.q.vex]]
82```
84#### Examples
86```
87> (rose "!" zap)
88[%.y p=[~ u='!']]
90> (rose "?" zap)
91[%.n p=0]
93> (rose "!?" zap)
94[%.n p=1]
96> (rose "!" ;~(plug zap fail))
97[%.y p=~]
98```
100---
102## `++rush`
104Parse or null
106Parse an atom with a given rule and produce null if the cord isn't
107entirely parsed.
109#### Accepts
111`naf` is an atom.
113`sab` is a rule.
115#### Produces
117The value of the parse result, or null.
119#### Source
121```hoon
122++ rush |*([naf=@ sab=rule] (rust (trip naf) sab))
123```
125#### Examples
127```
128> (rush 'I was the world in which I walked, and what I saw' (star (shim 0 200)))
129[~ "I was the world in which I walked, and what I saw"]
131> (rush 'abc' (just 'a'))
134> (rush 'abc' (jest 'abc'))
135[~ 'abc']
137> (rush 'abc' (jest 'ac'))
140> (rush 'abc' (jest 'ab'))
142```
144---
146## `++rust`
148Parse tape or null
150Parse a `tape` with a given `rule` and produce null if the `tape` isn't
151entirely parsed.
153#### Accepts
155`los` is a `tape`.
157`sab` is a `rule`.
159#### Produces
161A `(unit *)`, where `*` is the type produced by `sab`.
163#### Source
165```hoon
166++ rust |* [los=tape sab=rule]
167 =+ vex=((full sab) [[1 1] los])
168 ?~(q.vex ~ [~ u=p.u.q.vex])
169```
171#### Examples
173```
174> (rust "I was the world in which I walked, and what I saw" (star (shim 0 200)))
175[~ "I was the world in which I walked, and what I saw"]
177> (rust "Or heard or felt came not but from myself;" (star (shim 0 200)))
178[~ "Or heard or felt came not but from myself;"]
180> (rust "And there I found myself more truly and more strange." (jest 'And there I'))
182```
184---
186## `++scan`
188Parse tape or crash
190Parse a `tape` with a given `rule` and crash if the `tape` isn't entirely
191parsed.
193#### Accepts
195`los` is a `tape`.
197`sab` is a `rule`.
199#### Produces
201Either a `tape` or a crash.
203#### Source
205```hoon
206++ scan |* [los=tape sab=rule]
207 =+ vex=((full sab) [[1 1] los])
208 ?~ q.vex
209 ~_ (show [%m '{%d %d}'] p.p.vex q.p.vex ~)
210 ~_(leaf+"syntax error" !!)
211 p.u.q.vex
212```
214#### Examples
216```
217> (scan "I was the world in which I walked, and what I saw" (star (shim 0 200)))
218"I was the world in which I walked, and what I saw"
220> (scan "Or heard or felt came not but from myself;" (star (shim 0 200)))
221"Or heard or felt came not but from myself;"
223> (scan "And there I found myself more truly and more strange." (jest 'And there I'))
224! {1 12}
225! 'syntax-error'
226! exit
227```
229---