git.iko.soy/urbit.org
on b93c19b help sign in
urbit.org/reference/library/4i.md
1053 lines 16 kB history raw
1+++
2title = "4i: Parsing (Useful Idioms)"
3weight = 36
4template = "doc.html"
5+++
6### `++alf`
8Alphabetic characters
10Parse alphabetic characters, both upper and lowercase.
12#### Source
14```
15 ++ alf ;~(pose low hig) :: alphabetic
16```
18#### Examples
20```
21 > (scan "a" alf)
22 ~~a
24 > (scan "A" alf)
25 ~~~41.
27 > (scan "AaBbCc" (star alf))
28 "AaBbCc"
29```
32---
33### `++aln`
35Alphanumeric characters
37Parse alphanumeric characters - both alphabetic characters and numbers.
39#### Source
41```
42 ++ aln ;~(pose low hig nud) :: alphanumeric
43```
45#### Examples
47```
48 > (scan "0" aln)
49 ~~0
51 > (scan "alf42" (star aln))
52 "alf42"
54 > (scan "0123456789abcdef" (star aln))
55 "0123456789abcdef"
56```
59---
60### `++alp`
62Alphanumeric and `-`
64Parse alphanumeric strings and hep, "-".
66#### Source
68```
69 ++ alp ;~(pose low hig nud hep) :: alphanumeric and -
70```
72#### Examples
74```
75 > (scan "7" alp)
76 ~~7
78 > (scan "s" alp)
79 ~~s
81 > (scan "123abc-" (star alp))
82 "123abc-"
83```
86---
88### `++bet`
90Axis syntax `-`, `+`
92Parse the hep and lus axis syntax.
94#### Source
96```
97 ++ bet ;~(pose (cold 2 hep) (cold 3 lus)) :: axis syntax - +
98```
100#### Examples
102```
103 > (scan "-" bet)
104 2
106 > (scan "+" bet)
107 3
108```
111---
112### `++bin`
114Binary to atom
116Parse a tape of binary (0s and 1s) and produce its atomic representation.
118#### Source
120```
121 ++ bin (bass 2 (most gon but)) :: binary to atom
122```
124#### Examples
126```
127 > (scan "0000" bin)
128 0
130 > (scan "0001" bin)
131 1
133 > (scan "0010" bin)
134 2
136 > (scan "100000001111" bin)
137 2.063
138```
141---
142### `++but`
144Binary digit
146Parse a single binary digit.
148#### Source
150```
151 ++ but (cook |=(a=@ (sub a '0')) (shim '0' '1')) :: binary digit
152```
154#### Examples
156```
157 > (scan "0" but)
158 0
159 > (scan "1" but)
160 1
161 > (scan "01" but)
162 ! {1 2}
163 ! 'syntax-error'
164 ! exit
165 > (scan "01" (star but))
166 ~[0 1]
167```
170---
171### `++cit`
173Octal digit
175Parse a single octal digit.
177#### Source
179```
180 ++ cit (cook |=(a=@ (sub a '0')) (shim '0' '7')) :: octal digit
181```
183#### Examples
185```
186 > (scan "1" cit)
187 1
188 > (scan "7" cit)
189 7
190 > (scan "8" cit)
191 ! {1 1}
192 ! 'syntax-error'
193 ! exit
194 > (scan "60" (star cit))
195 ~[6 0]
196```
199---
200### `++dem`
202Decimal to atom
204Parse a decimal number to an atom.
206#### Source
208```
209 ++ dem (bass 10 (most gon dit)) :: decimal to atom
210```
212#### Examples
214```
215 > (scan "7" dem)
216 7
217 > (scan "42" dem)
218 42
219 > (scan "150000000" dem)
220 150.000.000
221 > (scan "12456" dem)
222 12.456
223```
226---
227### `++dit`
229Decimal digit
231Parse a single decimal digit.
233#### Source
235```
236 ++ dit (cook |=(a=@ (sub a '0')) (shim '0' '9')) :: decimal digit
237```
239#### Examples
241```
242 > (scan "7" dit)
243 7
244 > (scan "42" (star dit))
245 ~[4 2]
246 > (scan "26000" (star dit))
247 ~[2 6 0 0 0]
248```
251---
252### `++dog`
254`.` optional gap
256Dot followed by an optional gap, used with numbers.
258#### Source
260```
261 ++ dog ;~(plug dot gay) ::
262```
264#### Examples
266```
267 > 1.234.703
268 703
269 1.234.703
271 > (scan "a. " ;~(pfix alf dog))
272 [~~~. ~]
273```
276---
277### `++doh`
279`@p` separator
281Phonetic base phrase separator
283#### Source
285```
286 ++ doh ;~(plug ;~(plug hep hep) gay) ::
287```
289#### Examples
291```
292 /> ~nopfel-botduc-nilnev-dolfyn--haspub-natlun-lodmur-holtyd
293 ~nopfel-botduc-nilnev-dolfyn--haspub-natlun-lodmur-holtyd
294 /> ~nopfel-botduc-nilnev-dolfyn--
295 haspub-natlun-lodmur-holtyd
296 ~nopfel-botduc-nilnev-dolfyn--haspub-natlun-lodmur-holtyd
297 > (scan "--" doh)
298 [[~~- ~~-] ~]
299 > (scan "-- " doh)
300 [[~~- ~~-] ~]
301```
304---
305### `++dun`
307`--` to `~`
309Parse phep, `--`, to null, `~`.
311#### Source
313```
314 ++ dun (cold ~ ;~(plug hep hep)) :: -- (phep) to ~
315```
317#### Examples
319```
320 > (scan "--" dun)
321 ~
322 > (dun [[1 1] "--"])
323 [p=[p=1 q=3] q=[~ u=[p=~ q=[p=[p=1 q=3] q=""]]]]
324```
327---
329### `++duz`
331`==` to `~`
333Parse stet, `==`, to null `~`.
335#### Source
337```
338 ++ duz (cold ~ ;~(plug tis tis)) :: == (stet) to ~
339```
341#### Examples
343```
344 > (scan "==" duz)
345 ~
346 > (duz [[1 1] "== |=..."])
347 [p=[p=1 q=3] q=[~ u=[p=~ q=[p=[p=1 q=3] q=" |=..."]]]]
348```
351---
353### `++gah`
355Newline or ' '
357Whitespace component, either newline or space.
359#### Source
361```
362 ++ gah (mask [`@`10 ' ' ~]) :: newline or ace
363```
365#### Examples
367```
368 /> ^- * :: show spaces
369 """
370 -
371 -
372 -
373 """
374 [32 32 32 45 10 32 45 10 32 32 45 0]
375 /> ^- *
376 """
378 """
379 [32 32 32 10 32 10 32 32 0]
380 /> ^- (list ,@)
381 %- scan :_ (star gah)
382 """
384 """
385 ~[32 32 32 10 32 10 32 32]
386```
389---
390### `++gap`
392Plural whitespace
394Separates tall runes
396#### Source
398```
399 ++ gap (cold ~ ;~(plug gaq (star ;~(pose vul gah)))) :: plural whitespace
400```
403---
404### `++gaq`
406End of line
408Two spaces, a newline, or comment.
410#### Source
412```
413 ++ gaq ;~ pose :: end of line
414 (just `@`10)
415 ;~(plug gah ;~(pose gah vul))
416 vul
417 ==
418```
422---
423### `++gaw`
425Classic whitespace
427Terran whitespace.
429#### Source
431```
432 ++ gaw (cold ~ (star ;~(pose vul gah))) :: classic white
433```
436---
437### `++gay`
439Optional gap
441Optional gap.
443#### Source
445```
446 ++ gay ;~(pose gap (easy ~)) ::
447```
449---
450### `++gon`
452Long numbers
454Parse long numbers - Numbers which wrap around the shell with the line
456#### Source
458```
459 ++ gon ;~(pose ;~(plug bas gay fas) (easy ~)) :: long numbers \ /
460```
462#### Examples
464```
465 > (scan "\\/" gon)
466 [~~~5c. ~ ~~~2f.]
468 > (gon [[1 1] "\\/"])
469 [p=[p=1 q=3] q=[~ u=[p=[~~~5c. ~ ~~~2f.] q=[p=[p=1 q=3] q=""]]]]
470```
473---
474### `++gul`
476Axis syntax `<` or `>`
478Parse the axis gal and gar axis syntax.
480#### Source
482```
483 ++ gul ;~(pose (cold 2 gal) (cold 3 gar)) :: axis syntax < >
484```
486#### Examples
488```
489 > (scan "<" gul)
490 2
492 > (scan ">" gul)
493 3
494```
497---
498### `++hex`
500Hex to atom
502Parse any hexadecimal number to an atom.
504#### Source
506```
507 ++ hex (bass 16 (most gon hit)) :: hex to atom
508```
510#### Examples
512```
513 > (scan "a" hex)
514 10
515 > (scan "A" hex)
516 10
517 > (scan "2A" hex)
518 42
519 > (scan "1ee7" hex)
520 7.911
521 > (scan "1EE7" hex)
522 7.911
523 > (scan "1EE7F7" hex)
524 2.025.463
525 > `@ux`(scan "1EE7F7" hex)
526 0x1e.e7f7
527```
529---
530### `++hig`
532Uppercase
534Parse a single uppercase letter.
536#### Source
538```
539 ++ hig (shim 'A' 'Z') :: uppercase
540```
542#### Examples
544```
545 > (scan "G" hig)
546 ~~~47.
548 > `cord`(scan "G" hig)
549 'G'
551 > (scan "ABCDEFGHIJKLMNOPQRSTUVWXYZ" (star hig))
552 "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
554 > (hig [[1 1] "G"])
555 [p=[p=1 q=2] q=[~ [p=~~~47. q=[p=[p=1 q=2] q=""]]]]
556```
559---
560### `++hit`
562Hex digits
564Parse a single hexadecimal digit.
566#### Source
568```
569 ++ hit ;~ pose :: hex digits
570 dit
571 (cook |=(a=char (sub a 87)) (shim 'a' 'f'))
572 (cook |=(a=char (sub a 55)) (shim 'A' 'F'))
573 ==
574```
576#### Examples
578```
579 > (scan "a" hit)
580 10
581 > (scan "A" hit)
582 10
583 > (hit [[1 1] "a"])
584 [p=[p=1 q=2] q=[~ [p=10 q=[p=[p=1 q=2] q=""]]]]
585 > (scan "2A" (star hit))
586 ~[2 10]
587```
589---
590### `++iny`
592Indentation block
594Apply `++rule` to indented block starting at current column number, omitting
595the leading whitespace.
597#### Accepts
599`sef` is a `++rule`
601#### Produces
603A `++rule`.
605#### Source
607```
608 ++ inde |* sef/rule :: indentation block
609 |= nail ^+ (sef)
610 =+ [har tap]=[p q]:+<
611 =+ lev=(fil 3 (dec q.har) ' ')
612 =+ eol=(just `@t`10)
613 =+ =- roq=((star ;~(pose prn ;~(sfix eol (jest lev)) -)) har tap)
614 ;~(simu ;~(plug eol eol) eol)
615 ?~ q.roq roq
616 =+ vex=(sef har(q 1) p.u.q.roq)
617 =+ fur=p.vex(q (add (dec q.har) q.p.vex))
618 ?~ q.vex vex(p fur)
619 =- vex(p fur, u.q -)
620 :+ &3.vex
621 &4.vex(q.p (add (dec q.har) q.p.&4.vex))
622 =+ res=|4.vex
623 |- ?~ res |4.roq
624 ?. =(10 -.res) [-.res $(res +.res)]
625 (welp [`@t`10 (trip lev)] $(res +.res))
626 ::
627```
629#### Examples
631```
632 > (scan "abc" (iny (star ;~(pose prn (just `@`10)))))
633 "abc"
634 > (scan "abc" (star ;~(pose prn (just `@`10))))
635 "abc"
636 > (scan " abc\0ade" ;~(pfix ace ace (star ;~(pose prn (just `@`10)))))
637 "abc
638 de"
639 > (scan " abc\0ade" ;~(pfix ace ace (iny (star ;~(pose prn (just `@`10))))))
640 ! {1 6}
641 ! exit
642 > (scan " abc\0a de" ;~(pfix ace ace (iny (star ;~(pose prn (just `@`10))))))
643 "abc
644 de"
645```
648---
649### `++low`
651Lowercase
653Parse a single lowercase letter.
655#### Source
657```
658 ++ low (shim 'a' 'z') :: lowercase
659```
661#### Examples
663```
664 > (scan "g" low)
665 ~~g
666 > `cord`(scan "g" low)
667 'g'
668 > (scan "abcdefghijklmnopqrstuvwxyz" (star low))
669 "abcdefghijklmnopqrstuvwxyz"
670 > (low [[1 1] "g"])
671 [p=[p=1 q=2] q=[~ [p=~~g q=[p=[p=1 q=2] q=""]]]]
672```
675---
676### `++mes`
678Hexbyte
680Parse a hexbyte.
682#### Source
684```
685 ++ mes %+ cook :: hexbyte
686 |=({a/@ b/@} (add (mul 16 a) b))
687 ;~(plug hit hit)
688```
690#### Examples
692```
693 > (scan "2A" mes)
694 42
695 > (mes [[1 1] "2A"])
696 [p=[p=1 q=3] q=[~ u=[p=42 q=[p=[p=1 q=3] q=""]]]]
697 > (scan "42" mes)
698 66
699```
702---
703### `++nix`
705Letters and `-`
707Parse Letters and `-`.
709#### Source
711```
712 ++ nix (boss 256 (star ;~(pose aln cab))) ::
713```
715#### Examples
717```
718 > (scan "as_me" nix)
719 q=435.626.668.897
721 > `@t`(scan "as_me" nix)
722 'as_me'
723```
726---
728### `++nud`
730Numeric
732Parse a numeric character - A number.
734#### Source
736```
737 ++ nud (shim '0' '9') :: numeric
738```
740#### Examples
742```
743 > (scan "0" nud)
744 ~~0
745 > (scan "7" nud)
746 ~~7
747 > (nud [[1 1] "1"])
748 [p=[p=1 q=2] q=[~ [p=~~1 q=[p=[p=1 q=2] q=""]]]]
749 > (scan "0123456789" (star nud))
750 "0123456789"
751```
753---
754### `++prn`
756Printable character
758Parse any printable character.
760#### Source
762```
763 ++ prn ;~(less (just `@`127) (shim 32 256))
764```
766#### Examples
768```
769 > (scan "h" prn)
770 ~~h
771 > (scan "!" prn)
772 ~~~21.
773 > (scan "\01" prn)
774 ! {1 1}
775 ! exit
776```
779---
780### `++qit`
782Chars in cord
784Parse an individual character to its cord atom representation.
786#### Source
788```
789 ++ qit ;~ pose :: chars in a cord
790 ;~(less bas soq prn)
791 ;~(pfix bas ;~(pose bas soq mes)) :: escape chars
792 ==
793```
795#### Examples
797```
798 > (scan "%" qit)
799 37
800 > `@t`(scan "%" qit)
801 '%'
802 > (scan "0" qit)
803 48
804 > (scan "E" qit)
805 69
806 > (scan "a" qit)
807 97
808 > (scan "\\0a" qit)
809 10
810 > `@ux`(scan "\\0a" qit)
811 0xa
812 > (scan "cord" (star qit))
813 ~[99 111 114 100]
814```
817---
818### `++qit`
820Chars in cord
822Parse an individual character to its cord atom representation.
824#### Source
826```
827 ++ qit ;~ pose :: chars in a cord
828 ;~(less bas soq prn)
829 ;~(pfix bas ;~(pose bas soq mes)) :: escape chars
830 ==
831```
833#### Examples
835```
836 > (scan "%" qit)
837 37
838 > `@t`(scan "%" qit)
839 '%'
840 > (scan "0" qit)
841 48
842 > (scan "E" qit)
843 69
844 > (scan "a" qit)
845 97
846 > (scan "\\0a" qit)
847 10
848 > `@ux`(scan "\\0a" qit)
849 0xa
850 > (scan "cord" (star qit))
851 ~[99 111 114 100]
852```
856---
857### `++qut`
859Cord
861Parse single-soq cord with `\{gap}/` anywhere in the middle, or triple-single
862quote (aka triple-soq) cord, between which must be in an indented block.
864#### Source
866```
867 ++ qut ;~ pose :: cord
868 ;~ less soqs
869 (ifix [soq soq] (boss 256 (more gon qit)))
870 ==
871 %- inde %+ ifix
872 :- ;~ plug soqs
873 ;~(pose ;~(plug (plus ace) vul) (just '\0a'))
874 ==
875 ;~(plug (just '\0a') soqs)
876 (boss 256 (star qat))
877 ==
878 ::
879```
881#### Examples
883```
884 > (scan "'cord'" qut)
885 q=1.685.221.219
886 > 'cord'
887 'cord'
888 > `@ud`'cord'
889 1.685.221.219
890 > '''
891 Heredoc isn't prohibited from containing quotes
892 '''
893 'Heredoc isn't prohibited from containing quotes'
894```
897---
898### `++soz`
900Delimiting `'''`
902Parse a triple-single quote, used for multiline strings.
904#### Source
906```
907 ++ soz ;~(plug soq soq soq) :: delimiting '''
908```
910#### Examples
912```
913 > (scan "'''" soz)
914 [~~~27. ~~~27. ~~~27.]
915 > (rash '"""' soz)
916 ! {1 1}
917 ! exit
918```
921---
922### `++sym`
924Term
926A term: a letter(lowercase), followed by letters, numbers, or `-`.
928#### Source
930```
931 ++ sym
932 %+ cook
933 |=(a=tape (rap 3 ^-((list ,@) a)))
934 ;~(plug low (star ;~(pose nud low hep)))
935 ::
936```
938#### Examples
940```
941 > (scan "sam-2" sym)
942 215.510.507.891
943 > `@t`(scan "sam-2" sym)
944 'sam-2'
945 > (scan "sym" sym)
946 7.174.515
947```
950---
951### `++ven`
953`+>-` axis syntax
955Axis syntax parser
957#### Source
959```
960 ++ ven ;~ (comp |=({a/@ b/@} (peg a b))) :: +>- axis syntax
961 bet
962 =+ hom=`?`|
963 |= tub/nail
964 ^- (like axis)
965 =+ vex=?:(hom (bet tub) (gul tub))
966 ?~ q.vex
967 [p.tub [~ 1 tub]]
968 =+ wag=$(p.tub p.vex, hom !hom, tub q.u.q.vex)
969 ?> ?=(^ q.wag)
970 [p.wag [~ (peg p.u.q.vex p.u.q.wag) q.u.q.wag]]
971 ==
972```
974#### Examples
976```
977 ~zod/arvo=/hoon/hoon> (scan "->+" ven)
978 11
980 ~zod/arvo=/hoon/hoon> `@ub`(scan "->+" ven)
981 0b1011
983 ~zod/arvo=/hoon/hoon> (peg (scan "->" ven) (scan "+" ven))
984 11
986 ~zod/arvo=/hoon/hoon> ->+:[[1 2 [3 4]] 5]
987 [3 4]
988```
991---
992### `++vit`
994Base64 digit
996Parse a standard base64 digit.
998#### Source
1000```
1001 ++ vit :: base64 digit
1002 ;~ pose
1003 (cook |=(a/@ (sub a 65)) (shim 'A' 'Z'))
1004 (cook |=(a/@ (sub a 71)) (shim 'a' 'z'))
1005 (cook |=(a/@ (add a 4)) (shim '0' '9'))
1006 (cold 62 (just '-'))
1007 (cold 63 (just '+'))
1008 ==
1009```
1011#### Examples
1013```
1014 ~zod/arvo=/hoon/hoon> (scan "C" vit)
1016 ~zod/arvo=/hoon/hoon> (scan "c" vit)
1017 28
1018 ~zod/arvo=/hoon/hoon> (scan "2" vit)
1019 54
1020 ~zod/arvo=/hoon/hoon> (scan "-" vit)
1021 62
1022```
1024---
1025### `++vul`
1027Comments to null
1029#### Source
1031```
1032 ++ vul %+ cold ~ :: comments
1033 ;~ plug col col
1034 (star prn)
1035 (just `@`10)
1036 ==
1037```
1039Parse comments and produce a null. Note that a comment must be ended
1040with a newline character.
1042#### Examples
1044```
1045 > (scan "::this is a comment \0a" vul)
1047 > (scan "::this is a comment " vul)
1048 ! {1 21}
1049 ! exit
1050```
1053---