git.iko.soy/urbit.org
on e0c66bf help sign in
urbit.org/content/docs/hoon/reference/stdlib/4i.md
1052 lines 16 kB history raw
1+++
2title = "4i: Parsing (Useful Idioms)"
3weight = 36
4template = "doc.html"
5+++
7## `++alf`
9Alphabetic characters
11Parse alphabetic characters, both upper and lowercase.
13#### Source
15```hoon
16 ++ alf ;~(pose low hig) :: alphabetic
17```
19#### Examples
21```
22 > (scan "a" alf)
23 ~~a
25 > (scan "A" alf)
26 ~~~41.
28 > (scan "AaBbCc" (star alf))
29 "AaBbCc"
30```
32---
34## `++aln`
36Alphanumeric characters
38Parse alphanumeric characters - both alphabetic characters and numbers.
40#### Source
42```hoon
43 ++ aln ;~(pose low hig nud) :: alphanumeric
44```
46#### Examples
48```
49 > (scan "0" aln)
50 ~~0
52 > (scan "alf42" (star aln))
53 "alf42"
55 > (scan "0123456789abcdef" (star aln))
56 "0123456789abcdef"
57```
59---
61## `++alp`
63Alphanumeric and `-`
65Parse alphanumeric strings and hep, "-".
67#### Source
69```hoon
70 ++ alp ;~(pose low hig nud hep) :: alphanumeric and -
71```
73#### Examples
75```
76 > (scan "7" alp)
77 ~~7
79 > (scan "s" alp)
80 ~~s
82 > (scan "123abc-" (star alp))
83 "123abc-"
84```
86---
88## `++bet`
90Axis syntax `-`, `+`
92Parse the hep and lus axis syntax.
94#### Source
96```hoon
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```
110---
112## `++bin`
114Binary to atom
116Parse a tape of binary (0s and 1s) and produce its atomic representation.
118#### Source
120```hoon
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```
140---
142## `++but`
144Binary digit
146Parse a single binary digit.
148#### Source
150```hoon
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```
169---
171## `++cit`
173Octal digit
175Parse a single octal digit.
177#### Source
179```hoon
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```
198---
200## `++dem`
202Decimal to atom
204Parse a decimal number to an atom.
206#### Source
208```hoon
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```
225---
227## `++dit`
229Decimal digit
231Parse a single decimal digit.
233#### Source
235```hoon
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```
250---
252## `++dog`
254`.` optional gap
256Dot followed by an optional gap, used with numbers.
258#### Source
260```hoon
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```
275---
277## `++doh`
279`@p` separator
281Phonetic base phrase separator
283#### Source
285```hoon
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```
303---
305## `++dun`
307`--` to `~`
309Parse phep, `--`, to null, `~`.
311#### Source
313```hoon
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```
326---
328## `++duz`
330`==` to `~`
332Parse stet, `==`, to null `~`.
334#### Source
336```hoon
337 ++ duz (cold ~ ;~(plug tis tis)) :: == (stet) to ~
338```
340#### Examples
342```
343 > (scan "==" duz)
344 ~
345 > (duz [[1 1] "== |=..."])
346 [p=[p=1 q=3] q=[~ u=[p=~ q=[p=[p=1 q=3] q=" |=..."]]]]
347```
349---
351## `++gah`
353Newline or ' '
355Whitespace component, either newline or space.
357#### Source
359```hoon
360 ++ gah (mask [`@`10 ' ' ~]) :: newline or ace
361```
363#### Examples
365```
366 /> ^- * :: show spaces
367 """
368 -
369 -
370 -
371 """
372 [32 32 32 45 10 32 45 10 32 32 45 0]
373 /> ^- *
374 """
376 """
377 [32 32 32 10 32 10 32 32 0]
378 /> ^- (list ,@)
379 %- scan :_ (star gah)
380 """
382 """
383 ~[32 32 32 10 32 10 32 32]
384```
386---
388## `++gap`
390Plural whitespace
392Separates tall runes
394#### Source
396```hoon
397 ++ gap (cold ~ ;~(plug gaq (star ;~(pose vul gah)))) :: plural whitespace
398```
400---
402## `++gaq`
404End of line
406Two spaces, a newline, or comment.
408#### Source
410```hoon
411 ++ gaq ;~ pose :: end of line
412 (just `@`10)
413 ;~(plug gah ;~(pose gah vul))
414 vul
415 ==
416```
418---
420## `++gaw`
422Classic whitespace
424Terran whitespace.
426#### Source
428```hoon
429 ++ gaw (cold ~ (star ;~(pose vul gah))) :: classic white
430```
432---
434## `++gay`
436Optional gap
438Optional gap.
440#### Source
442```hoon
443 ++ gay ;~(pose gap (easy ~)) ::
444```
446---
448## `++gon`
450Long numbers
452Parse long numbers - Numbers which wrap around the shell with the line
454#### Source
456```hoon
457 ++ gon ;~(pose ;~(plug bas gay fas) (easy ~)) :: long numbers \ /
458```
460#### Examples
462```
463 > (scan "\\/" gon)
464 [~~~5c. ~ ~~~2f.]
466 > (gon [[1 1] "\\/"])
467 [p=[p=1 q=3] q=[~ u=[p=[~~~5c. ~ ~~~2f.] q=[p=[p=1 q=3] q=""]]]]
468```
470---
472## `++gul`
474Axis syntax `<` or `>`
476Parse the axis gal and gar axis syntax.
478#### Source
480```hoon
481 ++ gul ;~(pose (cold 2 gal) (cold 3 gar)) :: axis syntax < >
482```
484#### Examples
486```
487 > (scan "<" gul)
488 2
490 > (scan ">" gul)
491 3
492```
494---
496## `++hex`
498Hex to atom
500Parse any hexadecimal number to an atom.
502#### Source
504```hoon
505 ++ hex (bass 16 (most gon hit)) :: hex to atom
506```
508#### Examples
510```
511 > (scan "a" hex)
512 10
513 > (scan "A" hex)
514 10
515 > (scan "2A" hex)
516 42
517 > (scan "1ee7" hex)
518 7.911
519 > (scan "1EE7" hex)
520 7.911
521 > (scan "1EE7F7" hex)
522 2.025.463
523 > `@ux`(scan "1EE7F7" hex)
524 0x1e.e7f7
525```
527---
529## `++hig`
531Uppercase
533Parse a single uppercase letter.
535#### Source
537```hoon
538 ++ hig (shim 'A' 'Z') :: uppercase
539```
541#### Examples
543```
544 > (scan "G" hig)
545 ~~~47.
547 > `cord`(scan "G" hig)
548 'G'
550 > (scan "ABCDEFGHIJKLMNOPQRSTUVWXYZ" (star hig))
551 "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
553 > (hig [[1 1] "G"])
554 [p=[p=1 q=2] q=[~ [p=~~~47. q=[p=[p=1 q=2] q=""]]]]
555```
557---
559## `++hit`
561Hex digits
563Parse a single hexadecimal digit.
565#### Source
567```hoon
568 ++ hit ;~ pose :: hex digits
569 dit
570 (cook |=(a=char (sub a 87)) (shim 'a' 'f'))
571 (cook |=(a=char (sub a 55)) (shim 'A' 'F'))
572 ==
573```
575#### Examples
577```
578 > (scan "a" hit)
579 10
580 > (scan "A" hit)
581 10
582 > (hit [[1 1] "a"])
583 [p=[p=1 q=2] q=[~ [p=10 q=[p=[p=1 q=2] q=""]]]]
584 > (scan "2A" (star hit))
585 ~[2 10]
586```
588---
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```hoon
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```
647---
649## `++low`
651Lowercase
653Parse a single lowercase letter.
655#### Source
657```hoon
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```
674---
676## `++mes`
678Hexbyte
680Parse a hexbyte.
682#### Source
684```hoon
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```
701---
703## `++nix`
705Letters and `-`
707Parse Letters and `-`.
709#### Source
711```hoon
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```
725---
727## `++nud`
729Numeric
731Parse a numeric character - A number.
733#### Source
735```hoon
736 ++ nud (shim '0' '9') :: numeric
737```
739#### Examples
741```
742 > (scan "0" nud)
743 ~~0
744 > (scan "7" nud)
745 ~~7
746 > (nud [[1 1] "1"])
747 [p=[p=1 q=2] q=[~ [p=~~1 q=[p=[p=1 q=2] q=""]]]]
748 > (scan "0123456789" (star nud))
749 "0123456789"
750```
752---
754## `++prn`
756Printable character
758Parse any printable character.
760#### Source
762```hoon
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```
778---
780## `++qit`
782Chars in cord
784Parse an individual character to its cord atom representation.
786#### Source
788```hoon
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```
816---
818## `++qit`
820Chars in cord
822Parse an individual character to its cord atom representation.
824#### Source
826```hoon
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```
854---
856## `++qut`
858Cord
860Parse single-soq cord with `\{gap}/` anywhere in the middle, or triple-single
861quote (aka triple-soq) cord, between which must be in an indented block.
863#### Source
865```hoon
866 ++ qut ;~ pose :: cord
867 ;~ less soqs
868 (ifix [soq soq] (boss 256 (more gon qit)))
869 ==
870 %- inde %+ ifix
871 :- ;~ plug soqs
872 ;~(pose ;~(plug (plus ace) vul) (just '\0a'))
873 ==
874 ;~(plug (just '\0a') soqs)
875 (boss 256 (star qat))
876 ==
877 ::
878```
880#### Examples
882```
883 > (scan "'cord'" qut)
884 q=1.685.221.219
885 > 'cord'
886 'cord'
887 > `@ud`'cord'
888 1.685.221.219
889 > '''
890 Heredoc isn't prohibited from containing quotes
891 '''
892 'Heredoc isn't prohibited from containing quotes'
893```
895---
897## `++soz`
899Delimiting `'''`
901Parse a triple-single quote, used for multiline strings.
903#### Source
905```hoon
906 ++ soz ;~(plug soq soq soq) :: delimiting '''
907```
909#### Examples
911```
912 > (scan "'''" soz)
913 [~~~27. ~~~27. ~~~27.]
914 > (rash '"""' soz)
915 ! {1 1}
916 ! exit
917```
919---
921## `++sym`
923Term
925A term: a letter(lowercase), followed by letters, numbers, or `-`.
927#### Source
929```hoon
930 ++ sym
931 %+ cook
932 |=(a=tape (rap 3 ^-((list ,@) a)))
933 ;~(plug low (star ;~(pose nud low hep)))
934 ::
935```
937#### Examples
939```
940 > (scan "sam-2" sym)
941 215.510.507.891
942 > `@t`(scan "sam-2" sym)
943 'sam-2'
944 > (scan "sym" sym)
945 7.174.515
946```
948---
950## `++ven`
952`+>-` axis syntax
954Axis syntax parser
956#### Source
958```hoon
959 ++ ven ;~ (comp |=({a/@ b/@} (peg a b))) :: +>- axis syntax
960 bet
961 =+ hom=`?`|
962 |= tub/nail
963 ^- (like axis)
964 =+ vex=?:(hom (bet tub) (gul tub))
965 ?~ q.vex
966 [p.tub [~ 1 tub]]
967 =+ wag=$(p.tub p.vex, hom !hom, tub q.u.q.vex)
968 ?> ?=(^ q.wag)
969 [p.wag [~ (peg p.u.q.vex p.u.q.wag) q.u.q.wag]]
970 ==
971```
973#### Examples
975```
976 ~zod/arvo=/hoon/hoon> (scan "->+" ven)
977 11
979 ~zod/arvo=/hoon/hoon> `@ub`(scan "->+" ven)
980 0b1011
982 ~zod/arvo=/hoon/hoon> (peg (scan "->" ven) (scan "+" ven))
983 11
985 ~zod/arvo=/hoon/hoon> ->+:[[1 2 [3 4]] 5]
986 [3 4]
987```
989---
991## `++vit`
993Base64 digit
995Parse a standard base64 digit.
997#### Source
999```hoon
1000 ++ vit :: base64 digit
1001 ;~ pose
1002 (cook |=(a/@ (sub a 65)) (shim 'A' 'Z'))
1003 (cook |=(a/@ (sub a 71)) (shim 'a' 'z'))
1004 (cook |=(a/@ (add a 4)) (shim '0' '9'))
1005 (cold 62 (just '-'))
1006 (cold 63 (just '+'))
1007 ==
1008```
1010#### Examples
1012```
1013 ~zod/arvo=/hoon/hoon> (scan "C" vit)
1015 ~zod/arvo=/hoon/hoon> (scan "c" vit)
1016 28
1017 ~zod/arvo=/hoon/hoon> (scan "2" vit)
1018 54
1019 ~zod/arvo=/hoon/hoon> (scan "-" vit)
1020 62
1021```
1023---
1025## `++vul`
1027Comments to null
1029#### Source
1031```hoon
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```
1052---