git.iko.soy/urbit.org
on bfaa358 help sign in
urbit.org/docs/programming/reference/zuse/core/epur.md
885 lines 17 kB history raw
1### `++epur`
3Top-level URL parser
5Parses an entire URL.
7Accepts
8-------
10`a` is a [`++cord`](/doc/hoon/library/1#++cord).
12Produces
13--------
15A [`++purl`]().
17Source
18------
20 ++ epur :: url/header parser
21 =< |=(a=cord (rush a auri))
22 |%
24Examples
25--------
27 ~zod/main=> (epur 'http://127.0.0.1/')
28 [~ [p=[p=%.n q=~ r=[%.n p=.127.0.0.1]] q=[p=~ q=<||>] r=~]]
29 ~zod/main=> (epur 'http://www.google.com/')
30 [~ [p=[p=%.n q=~ r=[%.y p=<|com google www|>]] q=[p=~ q=<||>] r=~]]
31 ~zod/main=> (epur 'https://www.google.com/')
32 [~ [p=[p=%.y q=~ r=[%.y p=<|com google www|>]] q=[p=~ q=<||>] r=~]]
33 ~zod/main=> (epur 'https//www.google.com/')
34 ~
35 ~zod/main=> (epur 'https://www.google.com:200/')
36 [~ [p=[p=%.y q=[~ 200] r=[%.y p=<|com google www|>]] q=[p=~ q=<||>] r=~]]
37 ~zod/main=> (epur 'https://www.google.com:200/search')
38 [ ~
39 [p=[p=%.y q=[~ 200] r=[%.y p=<|com google www|>]] q=[p=~ q=<|search|>] r=~]
40 ]
41 ~zod/main=> (epur 'https://www.google.com/search')
42 [~ [p=[p=%.y q=~ r=[%.y p=<|com google www|>]] q=[p=~ q=<|search|>] r=~]]
43 ~zod/main=> (epur 'https://www.google.com/search?q=urbit')
44 [ ~
45 [ p=[p=%.y q=~ r=[%.y p=<|com google www|>]]
46 q=[p=~ q=<|search|>]
47 r=~[[p='q' q='urbit']]
48 ]
49 ]
50 ~zod/main=> (epur 'https://www.google.com/search?q=urb it')
51 ~
52 ~zod/main=> (epur 'https://www.google.com/search?q=urb%20it')
53 [ ~
54 [ p=[p=%.y q=~ r=[%.y p=<|com google www|>]]
55 q=[p=~ q=<|search|>]
56 r=~[[p='q' q='urb it']]
57 ]
58 ]
59 ~zod/main=> (epur 'https://www.google.com/search?q=urbit%20escaping%3F')
60 [ ~
61 [ p=[p=%.y q=~ r=[%.y p=<|com google www|>]]
62 q=[p=~ q=<|search|>]
63 r=~[[p='q' q='urbit escaping?']]
64 ]
65 ]
67### `++apat`
69URL path as ++pork
71Parses a URL path as a [`++pork`]().
73Produces
74--------
76A [`++rule`]().
78Source
79------
81 ++ apat :: 2396 abs_path
82 %+ cook deft
83 (ifix [fas ;~(pose fas (easy ~))] (more fas smeg))
85Examples
86--------
88 ~zod/try=> (scan "/foo/mol/lok" apat:epur)
89 [p=~ q=<|foo mol lok|>]
90 ~zod/try=> (scan "/foo/mol/lok.htm" apat:epur)
91 [p=[~ ~.htm] q=<|foo mol lok|>]
93### `++auri`
95URL parsing rule
97Accepts
98-------
100A [`++purl`]().
102Produces
103--------
105XX
107Source
108------
110 ++ auri
111 %+ cook
112 |= a=purl
113 ?.(=([& /localhost] r.p.a) a a(p.p &))
114 ;~ plug
115 ;~ plug
116 %+ sear
117 |= a=@t
118 ^- (unit ,?)
119 ?+(a ~ %http [~ %|], %https [~ %&])
120 ;~(sfix scem ;~(plug col fas fas))
121 thor
122 ==
123 ;~(plug ;~(pose apat (easy *pork)) yque)
124 ==
126Examples
127--------
129 ~zod/main=> (auri:epur [1 1] "http://127.0.0.1/")
130 [ p=[p=1 q=18]
131 q
132 [ ~
133 u
134 [ p=[p=[p=%.n q=~ r=[%.n p=.127.0.0.1]] q=[p=~ q=<||>] r=~]
135 q=[p=[p=1 q=18] q=""]
136 ]
137 ]
138 ]
139 ~zod/main=> (auri:epur [1 1] "http://www.google.com/")
140 [ p=[p=1 q=23]
141 q
142 [ ~
143 u
144 [ p=[p=[p=%.n q=~ r=[%.y p=<|com google www|>]] q=[p=~ q=<||>] r=~]
145 q=[p=[p=1 q=23] q=""]
146 ]
147 ]
148 ]
149 ~zod/main=> (auri:epur [1 1] "https://www.google.com/")
150 [ p=[p=1 q=24]
151 q
152 [ ~
153 u
154 [ p=[p=[p=%.y q=~ r=[%.y p=<|com google www|>]] q=[p=~ q=<||>] r=~]
155 q=[p=[p=1 q=24] q=""]
156 ]
157 ]
158 ]
159 ~zod/main=> (auri:epur [1 1] "https//www.google.com/")
160 [ p=[p=1 q=6] q=~]
161 ~zod/main=> (auri:epur [1 1] "https://www.google.com:200/")
162 [ p=[p=1 q=28]
163 q=[~ u=[p=[p=[p=%.y q=[~ 200] r=[%.y p=<|com google www|>]] q=[p=~ q=<||>] r=~] q=[p=[p=1 q=28] q=""]]]
164 ]
165 ~zod/main=> (auri:epur [1 1] "https://www.google.com:200/search")
166 [ p=[p=1 q=34]
167 q=[~ u=[p=[p=[p=%.y q=[~ 200] r=[%.y p=<|com google www|>]] q=[p=~ q=<|search|>] r=~] q=[p=[p=1 q=34] q=""]]]
168 ]
169 ~zod/main=> (auri:epur [1 1] "https://www.google.com/search")
170 [ p=[p=1 q=30]
171 q=[~ u=[p=[p=[p=%.y q=~ r=[%.y p=<|com google www|>]] q=[p=~ q=<|search|>] r=~] q=[p=[p=1 q=30] q=""]]]
172 ]
173 ~zod/main=> (auri:epur [1 1] "https://www.google.com/search?q=urbit")
174 [ p=[p=1 q=38]
175 q
176 [ ~
177 u
178 [ p=[p=[p=%.y q=~ r=[%.y p=<|com google www|>]] q=[p=~ q=<|search|>] r=~[[p='q' q='urbit']]]
179 q=[p=[p=1 q=38] q=""]
180 ]
181 ]
182 ]
183 ~zod/main=> (auri:epur [1 1] "https://www.google.com/search?q=urb it")
184 [ p=[p=1 q=36]
185 q
186 [ ~
187 u
188 [ p=[p=[p=%.y q=~ r=[%.y p=<|com google www|>]] q=[p=~ q=<|search|>] r=~[[p='q' q='urb']]]
189 q=[p=[p=1 q=36] q=" it"]
190 ]
191 ]
192 ]
193 ~zod/main=> (auri:epur [1 1] "https://www.google.com/search?q=urb%20it")
194 [ p=[p=1 q=41]
195 q
196 [ ~
197 u
198 [ p=[p=[p=%.y q=~ r=[%.y p=<|com google www|>]] q=[p=~ q=<|search|>] r=~[[p='q' q='urb it']]]
199 q=[p=[p=1 q=41] q=""]
200 ]
201 ]
202 ]
203 ~zod/main=> (auri:epur [1 1] "https://www.google.com/search?q=urbit%20escaping%3F")
204 [ p=[p=1 q=52]
205 q
206 [ ~
207 u
208 [ p=[p=[p=%.y q=~ r=[%.y p=<|com google www|>]] q=[p=~ q=<|search|>] r=~[[p='q' q='urbit escaping?']]]
209 q=[p=[p=1 q=52] q=""]
210 ]
211 ]
212 ]
214### `++cock`
216HTTP cookies, results in associative list of cord to cord.
218Accepts
219-------
221Produces
222--------
224Source
225------
227 ++ cock :: cookie
228 (most ;~(plug sem ace) ;~(plug toke ;~(pfix tis tosk)))
230Examples
231--------
233 ~zod/try=> (scan "sam=lop" cock:epur)
234 [['sam' 'lop'] ~]
235 ~zod/try=> (scan "sam=lop; res=\"salo don -keg!mo\"" cock:epur)
236 [['sam' 'lop'] ~[['res' 'salo don -keg!mo']]]
237 ~zod/try=> (scan "sam=lop; res=\"salo don -keg!mo\"; so" cock:epur)
238 ! {1 34}
239 ! exit
241### `++dlab`
243Domain label: alphanumeric, with `-` allowed in middle.
245Accepts
246-------
248Produces
249--------
251Source
252------
254 ++ dlab :: 2396 domainlabel
255 %+ sear
256 |= a=@ta
257 ?.(=('-' (rsh 3 (dec (met 3 a)) a)) [~ u=a] ~)
258 %+ cook cass
259 ;~(plug aln (star alp))
260 ::
262Examples
263--------
265 ~zod/try=> (scan "google" dlab:epur)
266 ~.google
267 ~zod/try=> (scan "lera2" dlab:epur)
268 ~.lera2
269 ~zod/try=> (scan "gor-tem" dlab:epur)
270 ~.gor-tem
271 ~zod/try=> (scan "gortem-" dlab:epur)
272 ! {1 8}
273 ! exit
275### `++fque`
277One or more query string characters
279Accepts
280-------
282Produces
283--------
285Source
286------
288 ++ fque (cook crip (plus pquo)) :: normal query field
290Examples
291--------
293 ~zod/try=> (scan "%20" fque:epur)
294 ' '
295 ~zod/try=> (scan "sam" fque:epur)
296 'sam'
297 ~zod/try=> (scan "les+tor" fque:epur)
298 'les tor'
299 ~zod/try=> (scan "sore-%22mek%22" fque:epur)
300 'sore-"mek"'
301 ~zod/try=> (scan "" fque:epur)
302 ! {1 1}
303 ! exit
305### `++fquu`
307Zero or more query string characters
309Accepts
310-------
312Produces
313--------
315Source
316------
318 ++ fquu (cook crip (star pquo)) :: optional field
320Examples
321--------
323 ~zod/try=> (scan "%20" fquu:epur)
324 ' '
325 ~zod/try=> (scan "sam" fquu:epur)
326 'sam'
327 ~zod/try=> (scan "les+tor" fquu:epur)
328 'les tor'
329 ~zod/try=> (scan "sore-%22mek%22" fquu:epur)
330 'sore-"mek"'
331 ~zod/try=> (scan "" fquu:epur)
332 ''
334### `++pcar`
336Single URL path character: literal, `%` escape, subpath delimiter, `:`
337or `@`
339Accepts
340-------
342Produces
343--------
345Source
346------
348 ++ pcar ;~(pose pure pesc psub col pat) :: 2396 path char
350Examples
351--------
353 ~zod/try=> (scan "a" pcar:epur)
354 ~~a
355 ~zod/try=> (scan "ab" pcar:epur)
356 ! {1 2}
357 ! exit
358 ~zod/try=> (scan "-" pcar:epur)
359 ~~-
360 ~zod/try=> (scan "." pcar:epur)
361 ~~~.
362 ~zod/try=> (scan "%20" pcar:epur)
363 ~~.
364 ~zod/try=> (scan "!" pcar:epur)
365 ~~~21.
367### `++pcok`
369Cookie character
371Accepts
372-------
374Produces
375--------
377Source
378------
380 ++ pcok ;~(less bas sem com doq prn) :: cookie char
382Examples
383--------
385 ~zod/try=> (scan "a" pcok:epur)
386 ~~a
387 ~zod/try=> (scan "ab" pcok:epur)
388 ! {1 2}
389 ! exit
390 ~zod/try=> (scan "!" pcok:epur)
391 ~~~21.
392 ~zod/try=> (scan ";" pcok:epur)
393 ! {1 2}
394 ! exit
396### `++pesc`
398URL `%` escape, by two hex characters.
400Accepts
401-------
403Produces
404--------
406Source
407------
409 ++ pesc ;~(pfix cen mes) :: 2396 escaped
411Examples
412--------
414 ~zod/try=> `@t`(scan "%22" pesc:epur)
415 '"'
416 ~zod/try=> `@t`(scan "%20" pesc:epur)
417 ' '
419### `++pold`
421Old URL `' '` escape
423Accepts
424-------
426Produces
427--------
429Source
430------
432 ++ pold (cold ' ' (just '+')) :: old space code
434Examples
435--------
437 ~zod/try=> `@t`(scan "+" pold:epur)
438 ' '
439 ~zod/try=> `@t`(scan " " pold:epur)
440 ! {1 1}
441 ! exit
443### `++pque`
445Irregular query string character.
447Accepts
448-------
450Produces
451--------
453Source
454------
456 ++ pque ;~(pose pcar fas wut) :: 3986 query char
458Examples
459--------
461 ~zod/try=> `@t`(scan "a" pque:epur)
462 'a'
463 ~zod/try=> `@t`(scan "?" pque:epur)
464 '?'
465 ~zod/try=> `@t`(scan "%20" pque:epur)
466 ' '
467 ~zod/try=> `@t`(scan "+" pque:epur)
468 '+'
470### `++pquo`
472Character in query string key/value
474Accepts
475-------
477Produces
478--------
480Source
481------
483 ++ pquo ;~(pose pure pesc pold) :: normal query char
485Examples
486--------
488 ~zod/try=> (scan "a" pquo:epur)
489 'a'
490 ~zod/try=> (scan "ab" pquo:epur)
491 ! {1 2}
492 ! exit
493 ~zod/try=> (scan "%22" pquo:epur)
494 '"'
495 ~zod/try=> (scan "%20" pquo:epur)
496 ' '
497 ~zod/try=> (scan "+" pquo:epur)
498 ' '
500### `++pure`
502URL-safe character
504Accepts
505-------
507Produces
508--------
510Source
511------
513 ++ pure ;~(pose aln hep dot cab sig) :: 2396 unreserved
515Examples
516--------
518 ~zod/try=> (scan "a" pure:epur)
519 ~~a
520 ~zod/try=> (scan "%20" pure:epur)
521 ! {1 1}
522 ! exit
523 ~zod/try=> (scan "." pure:epur)
524 ~~~.
525 ~zod/try=> (scan "-" pure:epur)
526 ~~-
528### `++psub`
530URL path subdelimeter
532Accepts
533-------
535Produces
536--------
538Source
539------
541 ++ psub ;~ pose :: 3986 sub-delims
542 zap buc pam soq pel per
543 tar lus com sem tis
544 ==
546Examples
547--------
549 ~zod/try=> `@t`(scan "+" psub:epur)
550 '+'
551 ~zod/try=> `@t`(scan "(" psub:epur)
552 '('
553 ~zod/try=> `@t`(scan "$" psub:epur)
554 '$'
555 ~zod/try=> `@t`(scan "a" psub:epur)
556 ! {1 1}
557 ! exit
559### `++ptok`
561Character valid in HTTP token
563Accepts
564-------
566Produces
567--------
569Source
570------
572 ++ ptok ;~ pose :: 2616 token
573 aln zap hax buc cen pam soq tar lus
574 hep dot ket cab tec bar sig
575 ==
577Examples
578--------
580 ~zod/try=> `tape`(murn =+(a=' ' |-(`tape`?:(=(0x7f a) ~ [a $(a +(a))]))) (curr rush ptok):epur)
581 "!#$%&'*+-.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ^_`abcdefghijklmnopqrstuvwxyz|~"
582 ~zod/try=> `tape`(skim =+(a=' ' |-(`tape`?:(=(0x7f a) ~ [a $(a +(a))]))) |=(a=char ?=(~ (rush a ptok:epur))))
583 " "(),/:;<=>?@[\]{}"
585### `++scem`
587URI scheme: alphabetic character, followed by any number of
588alphanumeric, `+` `-` or `.`
590Accepts
591-------
593Produces
594--------
596Source
597------
599 ++ scem :: 2396 scheme
600 %+ cook cass
601 ;~(plug alf (star ;~(pose aln lus hep dot)))
602 ::
604Examples
605--------
607 ~zod/try=> `@t`(scan "http" scem:epur)
608 'http'
609 ~zod/try=> `@t`(scan "https" scem:epur)
610 'https'
611 ~zod/try=> `@t`(scan "chrome-extension" scem:epur)
612 'chrome-extension'
614### `++smeg`
616URL path segment
618Accepts
619-------
621Produces
622--------
624Source
625------
627 ++ smeg (cook crip (plus pcar)) :: 2396 segment
629Examples
630--------
632 ~zod/try=> (scan "foo" smeg:epur)
633 'foo'
634 ~zod/try=> (scan "bar%20baz-bam" smeg:epur)
635 'bar baz-bam'
637### `++tock`
639HTTP cookie value
641Accepts
642-------
644Produces
645--------
647Source
648------
650 ++ tock (cook crip (plus pcok)) :: 6265 cookie-value
652Examples
653--------
655 ~zod/try=> (rush 'sam' tock:epur)
656 [~ 'sam']
657 ~zod/try=> (rush 'las!tore' tock:epur)
658 [~ 'las!tore']
659 ~zod/try=> (rush '"sop""les"tor' tock:epur)
660 ~
661 ~zod/try=> (rush '"zemug"' tock:epur)
662 ~
664### `++tosk`
666Possibly quoted HTTP cookie value
668Accepts
669-------
671Produces
672--------
674Source
675------
677 ++ tosk ;~(pose tock (ifix [doq doq] tock)) :: 6265 cookie-value
679Examples
680--------
682 ~zod/try=> (rush 'sam' tosk:epur)
683 [~ 'sam']
684 ~zod/try=> (rush 'las!tore' tosk:epur)
685 [~ 'las!tore']
686 ~zod/try=> (rush '"sop""les"tor' tosk:epur)
687 ~
688 ~zod/try=> (rush '"zemug"' tosk:epur)
689 [~ 'zemug']
691### `++toke`
693HTTP cookie name
695Accepts
696-------
698Produces
699--------
701Source
702------
704 ++ toke (cook crip (plus ptok)) :: 2616 token
706Examples
707--------
709 ~zod/try=> (rush 'sam' toke:epur)
710 [~ 'sam']
711 ~zod/try=> (rush 'las!tore' toke:epur)
712 [~ 'las!tore']
713 ~zod/try=> (rush 'sop""les"tor' toke:epur)
714 ~
715 ~zod/try=> (rush '"zemug"' toke:epur)
716 ~
718### `++thor`
720Parse ++host and unit `@ui` port.
722Accepts
723-------
725Produces
726--------
728Source
729------
731 ++ thor :: 2396 host/port
732 %+ cook |*(a=[* *] [+.a -.a])
733 ;~ plug
734 thos
735 ;~(pose (stag ~ ;~(pfix col dim:ag)) (easy ~))
736 ==
738Examples
739--------
741 ~zod/try=> (scan "localhost" thor:epur)
742 [~ [%.y i='localhost' t=~]]
743 ~zod/try=> (scan "localhost:8080" thor:epur)
744 [[~ q=8.080] [%.y i='localhost' t=~]]
745 ~zod/try=> (scan "192.168.0.1:8080" thor:epur)
746 [[~ q=8.080] [%.n q=3.232.235.521]]
747 ~zod/try=> (scan "www.google.com" thor:epur)
748 [~ [%.y i='com' t=~['google' 'www']]]
750### `++thos`
752URI host: dot-separated segments, or IP address.
754Accepts
755-------
757Produces
758--------
760Source
761------
763 ++ thos :: 2396 host, no local
764 ;~ plug
765 ;~ pose
766 %+ stag %&
767 %+ sear :: LL parser weak here
768 |= a=(list ,@t)
769 =+ b=(flop a)
770 ?> ?=(^ b)
771 =+ c=(end 3 1 i.b)
772 ?.(&((gte c 'a') (lte c 'z')) ~ [~ u=b])
773 (most dot dlab)
774 ::
775 %+ stag %|
776 =+ tod=(ape:ag ted:ab)
777 %+ bass 256
778 ;~(plug tod (stun [3 3] ;~(pfix dot tod)))
779 ==
780 ==
782Examples
783--------
785 ~zod/try=> (scan "localhost" thos:epur)
786 [%.y i='localhost' t=~]
787 ~zod/try=> (scan "192.168.0.1" thos:epur)
788 [%.n q=3.232.235.521]
789 ~zod/try=> (scan "192.168.0.1:80" thos:epur)
790 ! {1 12}
791 ! exit
792 ~zod/try=> (scan "www.google.com" thos:epur)
793 [%.y i='com' t=~['google' 'www']]
795### `++yque`
797Parses query string, or lack thereof. Result type ++quay
799Accepts
800-------
802Produces
803--------
805Source
806------
808 ++ yque :: query ending
809 ;~ pose
810 ;~(pfix wut yquy)
811 (easy ~)
812 ==
814Examples
815--------
817 ~zod/try=> (scan "?sar=tok" yque:epur)
818 [['sar' 'tok'] ~]
819 ~zod/try=> (scan "?les=urbit%20sep&met=kam" yque:epur)
820 [['les' 'urbit sep'] ~[['met' 'kam']]]
821 ~zod/try=> (scan "" yque:epur)
822 ~
824### `++yquy`
826Parse query string after `?`
828Accepts
829-------
831Produces
832--------
834Source
835------
837 ++ yquy :: query
838 ;~ pose :: proper query
839 %+ more
840 ;~(pose pam sem)
841 ;~(plug fque ;~(pose ;~(pfix tis fquu) (easy '')))
842 ::
843 %+ cook :: funky query
844 |=(a=tape [[%$ (crip a)] ~])
845 (star pque)
846 ==
848Examples
849--------
851 ~zod/try=> (scan "sar=tok" yquy:epur)
852 [['sar' 'tok'] ~]
853 ~zod/try=> (scan "les=urbit%20sep&met=kam" yquy:epur)
854 [['les' 'urbit sep'] ~[['met' 'kam']]]
855 ~zod/try=> (scan "" yquy:epur)
856 ~
858### `++zest`
860Parse ++quri absolute or relative request path
862Accepts
863-------
865Produces
866--------
868Source
869------
871 ++ zest :: 2616 request-uri
872 ;~ pose
873 (stag %& (cook |=(a=purl a) auri))
874 (stag %| ;~(plug apat yque))
875 ==
876 --
878Examples
879--------
881 ~zod/try=> (scan "http://www.google.com:80/search?q=foo" zest:epur)
882 [%.y p=[p=%.n q=[~ 80] r=[%.y p=<|com google www|>]] q=[p=~ q=<|search|>] r=~[[p='q' q='foo']]]
883 ~zod/try=> (scan "/rel/bat" zest:epur)
884 [%.n [p=~ q=<|rel bat|>] ~]