git.iko.soy/urbit.org
on b00decd help sign in
urbit.org/content/docs/hoon/reference/stdlib/4i.md
1054 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```
33---
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```
60---
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```
87---
89### `++bet`
91Axis syntax `-`, `+`
93Parse the hep and lus axis syntax.
95#### Source
97```hoon
98 ++ bet ;~(pose (cold 2 hep) (cold 3 lus)) :: axis syntax - +
99```
101#### Examples
103```
104 > (scan "-" bet)
105 2
107 > (scan "+" bet)
108 3
109```
112---
113### `++bin`
115Binary to atom
117Parse a tape of binary (0s and 1s) and produce its atomic representation.
119#### Source
121```hoon
122 ++ bin (bass 2 (most gon but)) :: binary to atom
123```
125#### Examples
127```
128 > (scan "0000" bin)
129 0
131 > (scan "0001" bin)
132 1
134 > (scan "0010" bin)
135 2
137 > (scan "100000001111" bin)
138 2.063
139```
142---
143### `++but`
145Binary digit
147Parse a single binary digit.
149#### Source
151```hoon
152 ++ but (cook |=(a=@ (sub a '0')) (shim '0' '1')) :: binary digit
153```
155#### Examples
157```
158 > (scan "0" but)
159 0
160 > (scan "1" but)
161 1
162 > (scan "01" but)
163 ! {1 2}
164 ! 'syntax-error'
165 ! exit
166 > (scan "01" (star but))
167 ~[0 1]
168```
171---
172### `++cit`
174Octal digit
176Parse a single octal digit.
178#### Source
180```hoon
181 ++ cit (cook |=(a=@ (sub a '0')) (shim '0' '7')) :: octal digit
182```
184#### Examples
186```
187 > (scan "1" cit)
188 1
189 > (scan "7" cit)
190 7
191 > (scan "8" cit)
192 ! {1 1}
193 ! 'syntax-error'
194 ! exit
195 > (scan "60" (star cit))
196 ~[6 0]
197```
200---
201### `++dem`
203Decimal to atom
205Parse a decimal number to an atom.
207#### Source
209```hoon
210 ++ dem (bass 10 (most gon dit)) :: decimal to atom
211```
213#### Examples
215```
216 > (scan "7" dem)
217 7
218 > (scan "42" dem)
219 42
220 > (scan "150000000" dem)
221 150.000.000
222 > (scan "12456" dem)
223 12.456
224```
227---
228### `++dit`
230Decimal digit
232Parse a single decimal digit.
234#### Source
236```hoon
237 ++ dit (cook |=(a=@ (sub a '0')) (shim '0' '9')) :: decimal digit
238```
240#### Examples
242```
243 > (scan "7" dit)
244 7
245 > (scan "42" (star dit))
246 ~[4 2]
247 > (scan "26000" (star dit))
248 ~[2 6 0 0 0]
249```
252---
253### `++dog`
255`.` optional gap
257Dot followed by an optional gap, used with numbers.
259#### Source
261```hoon
262 ++ dog ;~(plug dot gay) ::
263```
265#### Examples
267```
268 > 1.234.703
269 703
270 1.234.703
272 > (scan "a. " ;~(pfix alf dog))
273 [~~~. ~]
274```
277---
278### `++doh`
280`@p` separator
282Phonetic base phrase separator
284#### Source
286```hoon
287 ++ doh ;~(plug ;~(plug hep hep) gay) ::
288```
290#### Examples
292```
293 /> ~nopfel-botduc-nilnev-dolfyn--haspub-natlun-lodmur-holtyd
294 ~nopfel-botduc-nilnev-dolfyn--haspub-natlun-lodmur-holtyd
295 /> ~nopfel-botduc-nilnev-dolfyn--
296 haspub-natlun-lodmur-holtyd
297 ~nopfel-botduc-nilnev-dolfyn--haspub-natlun-lodmur-holtyd
298 > (scan "--" doh)
299 [[~~- ~~-] ~]
300 > (scan "-- " doh)
301 [[~~- ~~-] ~]
302```
305---
306### `++dun`
308`--` to `~`
310Parse phep, `--`, to null, `~`.
312#### Source
314```hoon
315 ++ dun (cold ~ ;~(plug hep hep)) :: -- (phep) to ~
316```
318#### Examples
320```
321 > (scan "--" dun)
322 ~
323 > (dun [[1 1] "--"])
324 [p=[p=1 q=3] q=[~ u=[p=~ q=[p=[p=1 q=3] q=""]]]]
325```
328---
330### `++duz`
332`==` to `~`
334Parse stet, `==`, to null `~`.
336#### Source
338```hoon
339 ++ duz (cold ~ ;~(plug tis tis)) :: == (stet) to ~
340```
342#### Examples
344```
345 > (scan "==" duz)
346 ~
347 > (duz [[1 1] "== |=..."])
348 [p=[p=1 q=3] q=[~ u=[p=~ q=[p=[p=1 q=3] q=" |=..."]]]]
349```
352---
354### `++gah`
356Newline or ' '
358Whitespace component, either newline or space.
360#### Source
362```hoon
363 ++ gah (mask [`@`10 ' ' ~]) :: newline or ace
364```
366#### Examples
368```
369 /> ^- * :: show spaces
370 """
371 -
372 -
373 -
374 """
375 [32 32 32 45 10 32 45 10 32 32 45 0]
376 /> ^- *
377 """
379 """
380 [32 32 32 10 32 10 32 32 0]
381 /> ^- (list ,@)
382 %- scan :_ (star gah)
383 """
385 """
386 ~[32 32 32 10 32 10 32 32]
387```
390---
391### `++gap`
393Plural whitespace
395Separates tall runes
397#### Source
399```hoon
400 ++ gap (cold ~ ;~(plug gaq (star ;~(pose vul gah)))) :: plural whitespace
401```
404---
405### `++gaq`
407End of line
409Two spaces, a newline, or comment.
411#### Source
413```hoon
414 ++ gaq ;~ pose :: end of line
415 (just `@`10)
416 ;~(plug gah ;~(pose gah vul))
417 vul
418 ==
419```
423---
424### `++gaw`
426Classic whitespace
428Terran whitespace.
430#### Source
432```hoon
433 ++ gaw (cold ~ (star ;~(pose vul gah))) :: classic white
434```
437---
438### `++gay`
440Optional gap
442Optional gap.
444#### Source
446```hoon
447 ++ gay ;~(pose gap (easy ~)) ::
448```
450---
451### `++gon`
453Long numbers
455Parse long numbers - Numbers which wrap around the shell with the line
457#### Source
459```hoon
460 ++ gon ;~(pose ;~(plug bas gay fas) (easy ~)) :: long numbers \ /
461```
463#### Examples
465```
466 > (scan "\\/" gon)
467 [~~~5c. ~ ~~~2f.]
469 > (gon [[1 1] "\\/"])
470 [p=[p=1 q=3] q=[~ u=[p=[~~~5c. ~ ~~~2f.] q=[p=[p=1 q=3] q=""]]]]
471```
474---
475### `++gul`
477Axis syntax `<` or `>`
479Parse the axis gal and gar axis syntax.
481#### Source
483```hoon
484 ++ gul ;~(pose (cold 2 gal) (cold 3 gar)) :: axis syntax < >
485```
487#### Examples
489```
490 > (scan "<" gul)
491 2
493 > (scan ">" gul)
494 3
495```
498---
499### `++hex`
501Hex to atom
503Parse any hexadecimal number to an atom.
505#### Source
507```hoon
508 ++ hex (bass 16 (most gon hit)) :: hex to atom
509```
511#### Examples
513```
514 > (scan "a" hex)
515 10
516 > (scan "A" hex)
517 10
518 > (scan "2A" hex)
519 42
520 > (scan "1ee7" hex)
521 7.911
522 > (scan "1EE7" hex)
523 7.911
524 > (scan "1EE7F7" hex)
525 2.025.463
526 > `@ux`(scan "1EE7F7" hex)
527 0x1e.e7f7
528```
530---
531### `++hig`
533Uppercase
535Parse a single uppercase letter.
537#### Source
539```hoon
540 ++ hig (shim 'A' 'Z') :: uppercase
541```
543#### Examples
545```
546 > (scan "G" hig)
547 ~~~47.
549 > `cord`(scan "G" hig)
550 'G'
552 > (scan "ABCDEFGHIJKLMNOPQRSTUVWXYZ" (star hig))
553 "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
555 > (hig [[1 1] "G"])
556 [p=[p=1 q=2] q=[~ [p=~~~47. q=[p=[p=1 q=2] q=""]]]]
557```
560---
561### `++hit`
563Hex digits
565Parse a single hexadecimal digit.
567#### Source
569```hoon
570 ++ hit ;~ pose :: hex digits
571 dit
572 (cook |=(a=char (sub a 87)) (shim 'a' 'f'))
573 (cook |=(a=char (sub a 55)) (shim 'A' 'F'))
574 ==
575```
577#### Examples
579```
580 > (scan "a" hit)
581 10
582 > (scan "A" hit)
583 10
584 > (hit [[1 1] "a"])
585 [p=[p=1 q=2] q=[~ [p=10 q=[p=[p=1 q=2] q=""]]]]
586 > (scan "2A" (star hit))
587 ~[2 10]
588```
590---
591### `++iny`
593Indentation block
595Apply `++rule` to indented block starting at current column number, omitting
596the leading whitespace.
598#### Accepts
600`sef` is a `++rule`
602#### Produces
604A `++rule`.
606#### Source
608```hoon
609 ++ inde |* sef/rule :: indentation block
610 |= nail ^+ (sef)
611 =+ [har tap]=[p q]:+<
612 =+ lev=(fil 3 (dec q.har) ' ')
613 =+ eol=(just `@t`10)
614 =+ =- roq=((star ;~(pose prn ;~(sfix eol (jest lev)) -)) har tap)
615 ;~(simu ;~(plug eol eol) eol)
616 ?~ q.roq roq
617 =+ vex=(sef har(q 1) p.u.q.roq)
618 =+ fur=p.vex(q (add (dec q.har) q.p.vex))
619 ?~ q.vex vex(p fur)
620 =- vex(p fur, u.q -)
621 :+ &3.vex
622 &4.vex(q.p (add (dec q.har) q.p.&4.vex))
623 =+ res=|4.vex
624 |- ?~ res |4.roq
625 ?. =(10 -.res) [-.res $(res +.res)]
626 (welp [`@t`10 (trip lev)] $(res +.res))
627 ::
628```
630#### Examples
632```
633 > (scan "abc" (iny (star ;~(pose prn (just `@`10)))))
634 "abc"
635 > (scan "abc" (star ;~(pose prn (just `@`10))))
636 "abc"
637 > (scan " abc\0ade" ;~(pfix ace ace (star ;~(pose prn (just `@`10)))))
638 "abc
639 de"
640 > (scan " abc\0ade" ;~(pfix ace ace (iny (star ;~(pose prn (just `@`10))))))
641 ! {1 6}
642 ! exit
643 > (scan " abc\0a de" ;~(pfix ace ace (iny (star ;~(pose prn (just `@`10))))))
644 "abc
645 de"
646```
649---
650### `++low`
652Lowercase
654Parse a single lowercase letter.
656#### Source
658```hoon
659 ++ low (shim 'a' 'z') :: lowercase
660```
662#### Examples
664```
665 > (scan "g" low)
666 ~~g
667 > `cord`(scan "g" low)
668 'g'
669 > (scan "abcdefghijklmnopqrstuvwxyz" (star low))
670 "abcdefghijklmnopqrstuvwxyz"
671 > (low [[1 1] "g"])
672 [p=[p=1 q=2] q=[~ [p=~~g q=[p=[p=1 q=2] q=""]]]]
673```
676---
677### `++mes`
679Hexbyte
681Parse a hexbyte.
683#### Source
685```hoon
686 ++ mes %+ cook :: hexbyte
687 |=({a/@ b/@} (add (mul 16 a) b))
688 ;~(plug hit hit)
689```
691#### Examples
693```
694 > (scan "2A" mes)
695 42
696 > (mes [[1 1] "2A"])
697 [p=[p=1 q=3] q=[~ u=[p=42 q=[p=[p=1 q=3] q=""]]]]
698 > (scan "42" mes)
699 66
700```
703---
704### `++nix`
706Letters and `-`
708Parse Letters and `-`.
710#### Source
712```hoon
713 ++ nix (boss 256 (star ;~(pose aln cab))) ::
714```
716#### Examples
718```
719 > (scan "as_me" nix)
720 q=435.626.668.897
722 > `@t`(scan "as_me" nix)
723 'as_me'
724```
727---
729### `++nud`
731Numeric
733Parse a numeric character - A number.
735#### Source
737```hoon
738 ++ nud (shim '0' '9') :: numeric
739```
741#### Examples
743```
744 > (scan "0" nud)
745 ~~0
746 > (scan "7" nud)
747 ~~7
748 > (nud [[1 1] "1"])
749 [p=[p=1 q=2] q=[~ [p=~~1 q=[p=[p=1 q=2] q=""]]]]
750 > (scan "0123456789" (star nud))
751 "0123456789"
752```
754---
755### `++prn`
757Printable character
759Parse any printable character.
761#### Source
763```hoon
764 ++ prn ;~(less (just `@`127) (shim 32 256))
765```
767#### Examples
769```
770 > (scan "h" prn)
771 ~~h
772 > (scan "!" prn)
773 ~~~21.
774 > (scan "\01" prn)
775 ! {1 1}
776 ! exit
777```
780---
781### `++qit`
783Chars in cord
785Parse an individual character to its cord atom representation.
787#### Source
789```hoon
790 ++ qit ;~ pose :: chars in a cord
791 ;~(less bas soq prn)
792 ;~(pfix bas ;~(pose bas soq mes)) :: escape chars
793 ==
794```
796#### Examples
798```
799 > (scan "%" qit)
800 37
801 > `@t`(scan "%" qit)
802 '%'
803 > (scan "0" qit)
804 48
805 > (scan "E" qit)
806 69
807 > (scan "a" qit)
808 97
809 > (scan "\\0a" qit)
810 10
811 > `@ux`(scan "\\0a" qit)
812 0xa
813 > (scan "cord" (star qit))
814 ~[99 111 114 100]
815```
818---
819### `++qit`
821Chars in cord
823Parse an individual character to its cord atom representation.
825#### Source
827```hoon
828 ++ qit ;~ pose :: chars in a cord
829 ;~(less bas soq prn)
830 ;~(pfix bas ;~(pose bas soq mes)) :: escape chars
831 ==
832```
834#### Examples
836```
837 > (scan "%" qit)
838 37
839 > `@t`(scan "%" qit)
840 '%'
841 > (scan "0" qit)
842 48
843 > (scan "E" qit)
844 69
845 > (scan "a" qit)
846 97
847 > (scan "\\0a" qit)
848 10
849 > `@ux`(scan "\\0a" qit)
850 0xa
851 > (scan "cord" (star qit))
852 ~[99 111 114 100]
853```
857---
858### `++qut`
860Cord
862Parse single-soq cord with `\{gap}/` anywhere in the middle, or triple-single
863quote (aka triple-soq) cord, between which must be in an indented block.
865#### Source
867```hoon
868 ++ qut ;~ pose :: cord
869 ;~ less soqs
870 (ifix [soq soq] (boss 256 (more gon qit)))
871 ==
872 %- inde %+ ifix
873 :- ;~ plug soqs
874 ;~(pose ;~(plug (plus ace) vul) (just '\0a'))
875 ==
876 ;~(plug (just '\0a') soqs)
877 (boss 256 (star qat))
878 ==
879 ::
880```
882#### Examples
884```
885 > (scan "'cord'" qut)
886 q=1.685.221.219
887 > 'cord'
888 'cord'
889 > `@ud`'cord'
890 1.685.221.219
891 > '''
892 Heredoc isn't prohibited from containing quotes
893 '''
894 'Heredoc isn't prohibited from containing quotes'
895```
898---
899### `++soz`
901Delimiting `'''`
903Parse a triple-single quote, used for multiline strings.
905#### Source
907```hoon
908 ++ soz ;~(plug soq soq soq) :: delimiting '''
909```
911#### Examples
913```
914 > (scan "'''" soz)
915 [~~~27. ~~~27. ~~~27.]
916 > (rash '"""' soz)
917 ! {1 1}
918 ! exit
919```
922---
923### `++sym`
925Term
927A term: a letter(lowercase), followed by letters, numbers, or `-`.
929#### Source
931```hoon
932 ++ sym
933 %+ cook
934 |=(a=tape (rap 3 ^-((list ,@) a)))
935 ;~(plug low (star ;~(pose nud low hep)))
936 ::
937```
939#### Examples
941```
942 > (scan "sam-2" sym)
943 215.510.507.891
944 > `@t`(scan "sam-2" sym)
945 'sam-2'
946 > (scan "sym" sym)
947 7.174.515
948```
951---
952### `++ven`
954`+>-` axis syntax
956Axis syntax parser
958#### Source
960```hoon
961 ++ ven ;~ (comp |=({a/@ b/@} (peg a b))) :: +>- axis syntax
962 bet
963 =+ hom=`?`|
964 |= tub/nail
965 ^- (like axis)
966 =+ vex=?:(hom (bet tub) (gul tub))
967 ?~ q.vex
968 [p.tub [~ 1 tub]]
969 =+ wag=$(p.tub p.vex, hom !hom, tub q.u.q.vex)
970 ?> ?=(^ q.wag)
971 [p.wag [~ (peg p.u.q.vex p.u.q.wag) q.u.q.wag]]
972 ==
973```
975#### Examples
977```
978 ~zod/arvo=/hoon/hoon> (scan "->+" ven)
979 11
981 ~zod/arvo=/hoon/hoon> `@ub`(scan "->+" ven)
982 0b1011
984 ~zod/arvo=/hoon/hoon> (peg (scan "->" ven) (scan "+" ven))
985 11
987 ~zod/arvo=/hoon/hoon> ->+:[[1 2 [3 4]] 5]
988 [3 4]
989```
992---
993### `++vit`
995Base64 digit
997Parse a standard base64 digit.
999#### Source
1001```hoon
1002 ++ vit :: base64 digit
1003 ;~ pose
1004 (cook |=(a/@ (sub a 65)) (shim 'A' 'Z'))
1005 (cook |=(a/@ (sub a 71)) (shim 'a' 'z'))
1006 (cook |=(a/@ (add a 4)) (shim '0' '9'))
1007 (cold 62 (just '-'))
1008 (cold 63 (just '+'))
1009 ==
1010```
1012#### Examples
1014```
1015 ~zod/arvo=/hoon/hoon> (scan "C" vit)
1017 ~zod/arvo=/hoon/hoon> (scan "c" vit)
1018 28
1019 ~zod/arvo=/hoon/hoon> (scan "2" vit)
1020 54
1021 ~zod/arvo=/hoon/hoon> (scan "-" vit)
1022 62
1023```
1025---
1026### `++vul`
1028Comments to null
1030#### Source
1032```hoon
1033 ++ vul %+ cold ~ :: comments
1034 ;~ plug col col
1035 (star prn)
1036 (just `@`10)
1037 ==
1038```
1040Parse comments and produce a null. Note that a comment must be ended
1041with a newline character.
1043#### Examples
1045```
1046 > (scan "::this is a comment \0a" vul)
1048 > (scan "::this is a comment " vul)
1049 ! {1 21}
1050 ! exit
1051```
1054---