content/docs/hoon/reference/stdlib/4i.md · urbit.org

git.iko.soy/urbit.org

on 4fdc19d help sign in

urbit.org/content/docs/hoon/reference/stdlib/4i.md

1086 lines 12 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)

17```

19#### Examples

21```

22> (scan "a" alf)

23'a'

25> (scan "A" alf)

26'A'

28> `tape`(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)

44```

46#### Examples

48```

49> (scan "0" aln)

50'0'

52> `tape`(scan "alf42" (star aln))

53"alf42"

54```

56---

58## `++alp`

60Alphanumeric and `-`

62Parse alphanumeric strings and hep, "-".

64#### Source

66```hoon

67++ alp ;~(pose low hig nud hep)

68```

70#### Examples

72```

73> (scan "7" alp)

74'7'

76> (scan "s" alp)

77's'

79> `tape`(scan "123abc-" (star alp))

80"123abc-"

81```

83---

85## `++bet`

87Axis syntax `-`, `+`

89Parse the hep and lus axis syntax.

91#### Source

93```hoon

94++ bet ;~(pose (cold 2 hep) (cold 3 lus))

95```

97#### Examples

99```

100> (scan "-" bet)

1012

102

103> (scan "+" bet)

1043

105```

107---

109## `++bin`

111Binary to atom

113Parse a tape of binary (0s and 1s) and produce its atomic representation.

114

115#### Source

116

117```hoon

118++ bin (bass 2 (most gon but))

119```

120

121#### Examples

122

123```

124> (scan "0000" bin)

1250

126

127> (scan "0001" bin)

1281

129

130> (scan "0010" bin)

1312

132

133> (scan "100000001111" bin)

1342.063

135```

137---

139## `++but`

141Binary digit

143Parse a single binary digit.

144

145#### Source

146

147```hoon

148++ but (cook |=(a=@ (sub a '0')) (shim '0' '1'))

149```

150

151#### Examples

152

153```

154> (scan "0" but)

1550

156

157> (scan "1" but)

1581

159

160> (scan "01" but)

161! {1 2}

162! 'syntax-error'

163! exit

164

165> (scan "01" (star but))

166~[0 1]

167```

169---

171## `++cit`

173Octal digit

175Parse a single octal digit.

176

177#### Source

178

179```hoon

180++ cit (cook |=(a=@ (sub a '0')) (shim '0' '7'))

181```

182

183#### Examples

184

185```

186> (scan "1" cit)

1871

188> (scan "7" cit)

1897

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.

205

206#### Source

207

208```hoon

209++ dem (bass 10 (most gon dit))

210```

211

212#### Examples

213

214```

215> (scan "7" dem)

2167

217

218> (scan "42" dem)

21942

220

221> (scan "150000000" dem)

222150.000.000

223

224> (scan "12456" dem)

22512.456

226```

228---

230## `++dit`

232Decimal digit

234Parse a single decimal digit.

235

236#### Source

237

238```hoon

239++ dit (cook |=(a=@ (sub a '0')) (shim '0' '9'))

240```

241

242#### Examples

243

244```

245> (scan "7" dit)

2467

247

248> (scan "42" (star dit))

249~[4 2]

250

251> (scan "26000" (star dit))

252~[2 6 0 0 0]

253```

255---

257## `++dog`

259`.` optional gap

261Dot followed by an optional gap, used with numbers.

262

263#### Source

264

265```hoon

266++ dog ;~(plug dot gay)

267```

268

269#### Examples

270

271```

272> (scan "." dog)

273['.' ~]

274

275> (scan "a. " ;~(pfix alf dog))

276['.' ~]

277```

279---

281## `++dof`

283`-` optional gap

285Hep followed by an optional gap, used with `@p` & `@q` syntax.

286

287#### Source

288

289```hoon

290++ dof ;~(plug hep gay)

291```

292

293#### Examples

294

295```

296> (scan "-" dof)

297['-' ~]

298

299> (scan "- " dof)

300['-' ~]

301```

303---

305## `++doh`

307`@p` separator

309Phonetic base phrase separator

310

311#### Source

312

313```hoon

314++ doh ;~(plug ;~(plug hep hep) gay)

315```

316

317#### Examples

318

319```

320> (scan "--" doh)

321[['-' '-'] ~]

322

323> (scan "-- " doh)

324[['-' '-'] ~]

325```

327---

329## `++dun`

331`--` to `~`

333Parse phep, `--`, to null, `~`.

334

335#### Source

336

337```hoon

338++ dun (cold ~ ;~(plug hep hep))

339```

340

341#### Examples

342

343```

344> (scan "--" dun)

345~

346```

348---

350## `++duz`

352`==` to `~`

354Parse stet, `==`, to null `~`.

355

356#### Source

357

358```hoon

359++ duz (cold ~ ;~(plug tis tis))

360```

361

362#### Examples

363

364```

365> (scan "==" duz)

366~

367```

369---

371## `++gah`

373Newline or ' '

375Whitespace component, either newline or space.

376

377#### Source

378

379```hoon

380++ gah (mask [`@`10 ' ' ~])

381```

382

383#### Examples

384

385```

386> `tape`(scan " \0a \0a" (star gah))

387" \0a \0a"

388```

390---

392## `++gap`

394Plural whitespace

396Separates tall runes

397

398#### Source

399

400```hoon

401++ gap (cold ~ ;~(plug gaq (star ;~(pose vul gah))))

402```

403

404#### Examples

405

406```

407> `tape`(scan " \0a \0a" gap)

408""

409

410> (scan "\0a \0a XYZ" ;~(pfix gap (jest 'XYZ')))

411'XYZ'

412```

414---

416## `++gaq`

418End of line

420Two spaces, a newline, or comment.

421

422#### Source

423

424```hoon

425++ gaq ;~ pose

426 (just `@`10)

427 ;~(plug gah ;~(pose gah vul))

428 vul

429 ==

430```

431

432#### Examples

433

434```

435> (scan "123\0a" ;~(sfix dem gaq))

436123

437

438> (scan "123 :: foo\0a" ;~(sfix dem gaq))

439123

440```

441

442---

443

444## `++gaw`

445

446Classic whitespace

447

448Terran whitespace.

449

450#### Source

451

452```hoon

453++ gaw (cold ~ (star ;~(pose vul gah)))

454```

455

456#### Examples

457

458```

459> (scan " \0a :: foo \0a" gaw)

460~

461

462> (scan " " gaw)

463~

464

465> (scan "\0a" gaw)

466~

467```

469---

471## `++gay`

473Optional gap

475Optional gap.

477#### Source

479```hoon

480++ gay ;~(pose gap (easy ~))

481```

482

483#### Examples

484

485```

486> (scan " " gay)

487~

488

489> (scan " " gay)

490~

491

492> (scan "\0a" gay)

493~

494

495> (scan "" gay)

496~

497```

499---

501## `++gon`

503Long numbers

505Parse long numbers - Numbers which wrap around the shell with the line

506

507#### Source

508

509```hoon

510++ gon ;~(pose ;~(plug bas gay fas) (easy ~))

511```

512

513#### Examples

514

515```

516> 'abc\

517 /def'

518'abcdef'

519

520> (scan "\\\0a/" gon)

521['\\' ~ '/']

522```

523

524---

525

526## `++gul`

527

528Axis syntax `<` or `>`

529

530Parse the axis gal and gar axis syntax.

531

532#### Source

533

534```hoon

535++ gul ;~(pose (cold 2 gal) (cold 3 gar))

536```

537

538#### Examples

539

540```

541> (scan "<" gul)

5422

543

544> (scan ">" gul)

5453

546```

548---

550## `++hex`

552Hex to atom

554Parse any hexadecimal number to an atom.

555

556#### Source

557

558```hoon

559++ hex (bass 16 (most gon hit))

560```

561

562#### Examples

563

564```

565> (scan "a" hex)

56610

567

568> (scan "A" hex)

56910

570

571> (scan "2A" hex)

57242

573

574> (scan "1ee7" hex)

5757.911

576

577> (scan "1EE7" hex)

5787.911

579

580> (scan "1EE7F7" hex)

5812.025.463

582

583> `@ux`(scan "1EE7F7" hex)

5840x1e.e7f7

585```

587---

589## `++hig`

591Uppercase

593Parse a single uppercase letter.

594

595#### Source

596

597```hoon

598++ hig (shim 'A' 'Z')

599```

600

601#### Examples

602

603```

604> (scan "G" hig)

605'G'

606

607> (scan "ABCDEFGHIJKLMNOPQRSTUVWXYZ" (star hig))

608"ABCDEFGHIJKLMNOPQRSTUVWXYZ"

609```

611---

613## `++hit`

615Hex digits

617Parse a single hexadecimal digit.

618

619#### Source

620

621```hoon

622++ hit ;~ pose

623 dit

624 (cook |=(a=char (sub a 87)) (shim 'a' 'f'))

625 (cook |=(a=char (sub a 55)) (shim 'A' 'F'))

626 ==

627```

628

629#### Examples

630

631```

632> (scan "a" hit)

63310

634

635> (scan "A" hit)

63610

637

638> (scan "2A" (star hit))

639~[2 10]

640```

642---

644## `++iny`

646Indentation block

648Apply `rule` to indented block starting at current column number, omitting

649the leading whitespace.

651#### Accepts

653`sef` is a `rule`

655#### Produces

657A `rule`.

659#### Source

661```hoon

662++ iny

663 |* sef=rule

664 |= nail ^+ (sef)

665 =+ [har tap]=[p q]:+<

666 =+ lev=(fil 3 (dec q.har) ' ')

667 =+ eol=(just `@t`10)

668 =+ =- roq=((star ;~(pose prn ;~(sfix eol (jest lev)) -)) har tap)

669 ;~(simu ;~(plug eol eol) eol)

670 ?~ q.roq roq

671 =+ vex=(sef har(q 1) p.u.q.roq)

672 =+ fur=p.vex(q (add (dec q.har) q.p.vex))

673 ?~ q.vex vex(p fur)

674 =- vex(p fur, u.q -)

675 :+ &3.vex

676 &4.vex(q.p (add (dec q.har) q.p.&4.vex))

677 =+ res=|4.vex

678 |- ?~ res |4.roq

679 ?. =(10 -.res) [-.res $(res +.res)]

680 (welp [`@t`10 (trip lev)] $(res +.res))

681```

682

683#### Examples

684

685```

686> `tape`(scan " foo\0a bar" ;~(pfix ace ace ace (iny (star ;~(pose prn (just '\0a'))))))

687"foo\0abar"

688```

689

690#### Discussion

691

692Note the amount of indentation whitespace to be stripped from the beginning of

693each line is determined by the value of `q` (the column) in the `hair` when

694`++iny` is first called. This means something like the `pfix` expression in the

695example above is necessary to set the level of indentation. Additionally, the

696`rule` given to `++iny` must consume the whole line including the line ending.

698---

700## `++low`

702Lowercase

704Parse a single lowercase letter.

705

706#### Source

707

708```hoon

709++ low (shim 'a' 'z')

710```

711

712#### Examples

713

714```

715> (scan "g" low)

716'g'

717```

719---

721## `++mes`

723Hexbyte

725Parse a hexbyte.

727#### Source

729```hoon

730++ mes %+ cook

731 |=({a/@ b/@} (add (mul 16 a) b))

732 ;~(plug hit hit)

733```

734

735#### Examples

736

737```

738> (scan "2A" mes)

73942

740

741> (scan "42" mes)

74266

743```

744

745---

746

747## `++nix`

748

749Letters and underscore

750

751Parse Letters and `_`.

752

753#### Source

754

755```hoon

756++ nix (boss 256 (star ;~(pose aln cab)))

757```

758

759#### Examples

760

761```

762> `@t`(scan "as_me" nix)

763'as_me'

764```

766---

768## `++nud`

770Numeric

772Parse a numeric character - A number.

773

774#### Source

775

776```hoon

777++ nud (shim '0' '9')

778```

779

780#### Examples

781

782```

783> (scan "0" nud)

784'0'

785

786> (scan "7" nud)

787'7'

788```

789

790---

791

792## `++prn`

793

794Printable character

795

796Parse any printable character.

797

798#### Source

799

800```hoon

801++ prn ;~(less (just `@`127) (shim 32 256))

802```

803

804#### Examples

805

806```

807> (scan "h" prn)

808'h'

809

810> (scan "!" prn)

811'!'

812

813> (scan "\01" prn)

814! {1 1}

815! exit

816```

817

818---

819

820## `++qat`

821

822Chars in blockcord

823

824Parse a single character contained in a mult-line cord block.

825

826#### Source

827

828```hoon

829++ qat ;~ pose

830 prn

831 ;~(less ;~(plug (just `@`10) soz) (just `@`10))

832 ==

833```

834

835#### Examples

836

837```

838> ^- tape

839 %+ scan

840 "'''\0aabc\0adef\0aghi\0a'''"

841 %+ ifix

842 :- ;~(plug soz (just `@`10))

843 ;~(plug (just `@`10) soz)

844 (star qat)

845"abc\0adef\0aghi"

846```

848---

850## `++qit`

852Chars in cord

854Parse an individual character to its cord atom representation. Escaped

855characters are converted to the value they represent.

856

857#### Source

858

859```hoon

860++ qit ;~ pose :: chars in a cord

861 ;~(less bas soq prn)

862 ;~(pfix bas ;~(pose bas soq mes)) :: escape chars

863 ==

864```

865

866#### Examples

867

868```

869> (scan "%" qit)

870'%'

871

872> `tape`(scan "cord" (star qit))

873"cord"

874

875> `tape`(scan "\\0a" (star qit))

876"\0a"

877```

879---

881## `++qut`

883Cord

885Parse single-soq cord with `\{gap}/` anywhere in the middle, or triple-single

886quote (aka triple-soq) cord, between which must be in an indented block.

887

888#### Source

889

890```hoon

891++ qut ;~ simu soq

892 ;~ pose

893 ;~ less soz

894 (ifix [soq soq] (boss 256 (more gon qit)))

895 ==

896 =+ hed=;~(pose ;~(plug (plus ace) vul) (just '\0a'))

897 %- iny %+ ifix

898 :- ;~(plug soz hed)

899 ;~(plug (just '\0a') soz)

900 (boss 256 (star qat))

901 ==

902 ==

903```

904

905#### Examples

906

907```

908> `@t`(scan "'cord'" qut)

909'cord'

910

911> `@t`(scan "'''\0aabc\0adef\0a'''" qut)

912'abc\0adef'

913```

915---

917## `++soz`

919Delimiting `'''`

921Parse a triple-single quote, used for multiline strings.

922

923#### Source

924

925```hoon

926++ soz ;~(plug soq soq soq)

927```

928

929#### Examples

930

931```

932> (scan "'''" soz)

933['\'' '\'' '\'']

934```

936---

938## `++sym`

940Term

942A term: a lowercase letter, followed by letters, numbers, or `-`.

943

944#### Source

945

946```hoon

947++ sym

948 %+ cook

949 |=(a=tape (rap 3 ^-((list @) a)))

950 ;~(plug low (star ;~(pose nud low hep)))

951```

952

953#### Examples

954

955```

956> `term`(scan "sam-2" sym)

957%sam-2

958```

959

960---

961

962## `++mixed-case-symbol`

963

964Mixed-case term

965

966The same as [`++sym`](#sym) but allowing uppercase letters.

967

968#### Source

969

970```hoon

971++ mixed-case-symbol

972 %+ cook

973 |=(a=tape (rap 3 ^-((list @) a)))

974 ;~(plug alf (star alp))

975```

976

977#### Examples

978

979```

980> `term`(scan "sAm-2" mixed-case-symbol)

981%sAm-2

982```

984---

986## `++ven`

988`+>-` axis syntax

990Axis syntax parser

991

992#### Source

993

994```hoon

995++ ven ;~ (comp |=([a=@ b=@] (peg a b)))

996 bet

997 =+ hom=`?`|

998 |= tub=nail

999 ^- (like @)

1000 =+ vex=?:(hom (bet tub) (gul tub))

1001 ?~ q.vex

1002 [p.tub [~ 1 tub]]

1003 =+ wag=$(p.tub p.vex, hom !hom, tub q.u.q.vex)

1004 ?> ?=(^ q.wag)

1005 [p.wag [~ (peg p.u.q.vex p.u.q.wag) q.u.q.wag]]

1006 ==

1007```

1008

1009#### Examples

1010

1011```

1012> (scan "->+" ven)

101311

1014

1015> (scan "->+<-" ven)

101644

1017```

1019---

1021## `++vit`

1023Base64 digit

1025Parse a standard base64 digit.

1026

1027#### Source

1028

1029```hoon

1030++ vit

1031 ;~ pose

1032 (cook |=(a=@ (sub a 65)) (shim 'A' 'Z'))

1033 (cook |=(a=@ (sub a 71)) (shim 'a' 'z'))

1034 (cook |=(a=@ (add a 4)) (shim '0' '9'))

1035 (cold 62 (just '-'))

1036 (cold 63 (just '+'))

1037 ==

1038```

1039

1040#### Examples

1041

1042```

1043> (scan "C" vit)

10442

1045

1046> (scan "c" vit)

104728

1048

1049> (scan "2" vit)

105054

1051

1052> (scan "-" vit)

105362

1054```

1056---

1058## `++vul`

1060Comments to null

1062Parse comments and produce a null. Note that a comment must be ended

1063with a newline character.

1064

1065#### Source

1066

1067```hoon

1068++ vul %+ cold ~

1069 ;~ plug col col

1070 (star prn)

1071 (just `@`10)

1072 ==

1073```

1074

1075#### Examples

1076

1077```

1078> (scan "::this is a comment \0a" vul)

1079~

1080

1081> (scan "::this is a comment " vul)

1082! {1 21}

1083! exit

1084```

1085

1086---