content/docs/hoon/reference/stdlib/5c.md · urbit.org

git.iko.soy/urbit.org

on 4fdc19d help sign in

urbit.org/content/docs/hoon/reference/stdlib/5c.md

925 lines 12 kB history raw

1+++

2title = "5c: Compiler Backend & Prettyprinter"

3weight = 45

4template = "doc.html"

5+++

7## `++ut`

9Hoon compiler backend

11#### Source

13This core is too large to include here, refer to `hoon.hoon` for the source.

15---

17## `++us`

19Pretty-printer backend

21#### Source

23This core is too large to include here, refer to `hoon.hoon` for the source.

25---

27## `++cain`

29Tank pretty-print

31Pretty-print a `vase` as a `tank` using `++deal`. This is the same as

32[`++sell`](#sell).

34#### Accepts

36A `vase`.

38#### Produces

40A `tank`.

42#### Source

44```hoon

45++ cain sell

46```

48#### Examples

50```

51> (cain !>(['foo' 'bar']))

52[%rose p=[p=" " q="[" r="]"] q=~[[%leaf p="'foo'"] [%leaf p="'bar'"]]]

53```

55---

57## `++noah`

59Tape pretty-print

61Pretty-print a `vase` as a `tape`. This is the same as [`++text`](#text).

63#### Accepts

65A `vase`.

67#### Produces

69A `tape`.

71#### Source

73```hoon

74++ noah text

75```

77#### Examples

79```

80> (noah !>(['foo' 'bar']))

81"['foo' 'bar']"

82```

84---

86## `++onan`

88Vise to vase

90Convert a `vise` (old `vase`) to the new `vase`. This is the same as

91[`++seer`](#seer).

93#### Accepts

95A `vise`.

97#### Produces

99A `vase`.

100

101#### Source

102

103```hoon

104++ onan seer

105```

106

107#### Examples

108

109```

110> (onan `vise`!>(['foo' 'bar']))

111[#t/[@t @t] q=[7.303.014 7.496.034]]

112```

113

114---

115

116## `++levi`

117

118Type nests or crash

119

120Check if type `b` nests under type `a`. Produces `%.y` if it nests and crashes

121if it does not.

123#### Accepts

125`a` is a `type`.

127`b` is a `type`.

129#### Produces

131A `?`.

133#### Source

135```hoon

136++ levi

137 |= [a=type b=type]

138 (~(nest ut a) & b)

139```

140

141#### Examples

142

143```

144> (levi -:!>('foo') -:!>(%foo))

145%.y

146

147> (levi -:!>(%foo) -:!>('foo'))

148-need.%foo

149-have.@t

150nest-fail

151```

153---

155## `++text`

157Tape pretty-print

159Pretty print vase `vax` as a `tape`.

160

161#### Accepts

162

163`vax` is a `vase`.

165#### Produces

167A `tape`.

169#### Source

171```hoon

172++ text

173 |= vax=vase ^- tape

174 ~(ram re (sell vax))

175```

176

177#### Examples

178

179```

180> (text !>(['foo' 'bar']))

181"['foo' 'bar']"

182```

184---

186## `++seem`

188Promote typo

190Convert `typo` (old type) to the new `type`.

191

192#### Accepts

193

194`toy` is a `typo`.

196#### Produces

198A `type`.

200#### Source

202```hoon

203++ seem |=(toy=typo `type`toy)

204```

205

206#### Examples

207

208```

209> (seem -:!>('foo'))

210#t/@t

211```

213---

215## `++seer`

217Promote vise

219Convert a `vise` (old `vase`) to the new `vase`.

220

221#### Accepts

222

223`vix` is a `vise`.

225#### Produces

227A `vase`.

229#### Source

231```hoon

232++ seer |=(vix=vise `vase`vix)

233```

234

235#### Examples

236

237```

238> (seer !>('foo'))

239[#t/@t q=7.303.014]

240```

241

242---

243

244## `++sell`

245

246Pretty-print vase to a tank

247

248Pretty-print vase `vax` to a `tank` using `++deal:us`.

249

250#### Accepts

251

252`vax` is a `vase`.

254#### Produces

256A `tank`.

258#### Source

260```hoon

261++ sell

262 ~/ %sell

263 |= vax=vase

264 ^- tank

265 ~| %sell

266 (~(deal us p.vax) q.vax)

267```

268

269#### Examples

270

271```

272> (sell !>(['foo' 'bar']))

273[%rose p=[p=" " q="[" r="]"] q=~[[%leaf p="'foo'"] [%leaf p="'bar'"]]]

274```

275

276---

277

278## `++skol`

279

280Pretty-print type to tank

281

282Pretty-print type `typ` to a `tank` using `++duck:ut`.

283

284#### Accepts

285

286`typ` is a `type`.

288#### Produces

290A `tank`.

292#### Source

294```hoon

295++ skol

296 |= typ=type

297 ^- tank

298 ~(duck ut typ)

299```

300

301#### Examples

302

303```

304> (skol -:!>(['foo' 'bar']))

305[%rose p=[p=" " q="[" r="]"] q=~[[%leaf p="@t"] [%leaf p="@t"]]]

306```

308---

310## `++slam`

312Slam a gate

314Slam `gat`, a gate in a `vase`, with `sam`, a sample in a `vase`. Produces a

315`vase` containing the result.

316

317#### Accepts

318

319`gat` is a gate in a `vase`.

320

321`sam` is a noun in a `vase`.

323#### Produces

325A `vase`.

327#### Source

329```hoon

330++ slam

331 |= [gat=vase sam=vase] ^- vase

332 =+ :- ^= typ ^- type

333 [%cell p.gat p.sam]

334 ^= gen ^- hoon

335 [%cnsg [%$ ~] [%$ 2] [%$ 3] ~]

336 =+ gun=(~(mint ut typ) %noun gen)

337 [p.gun (slum q.gat q.sam)]

338```

339

340#### Examples

341

342```

343> (slam !>(|=([a=@ud b=@ud] [b a])) !>([1 2]))

344[#t/[@ud @ud] q=[2 1]]

345```

347---

349## `++slab`

351Test if contains

353States whether you can access named wing `cog` in type `typ` using access method `way`.

354

355#### Accepts

356

357`way` is a `?(%read %rite %both)` (A `$vial` without `%free`). This represents

358the access method (read, write, or both read and write).

359

360`cog` is a `@tas`, the name of a wing.

361

362`typ` is a `type`.

364#### Produces

366A `?`.

368#### Source

370```hoon

371++ slab

372 |= [way=?(%read %rite %both) cog=@tas typ=type]

373 ?= [%& *]

374 (~(fond ut typ) way ~[cog])

375```

376

377```

378> =au |=(a=@ +(a))

379> (slab %read %a -:!>(au))

380%.y

381> (slab %rite %a -:!>(au))

382%.y

383> (slab %both %a -:!>(au))

384%.y

385

386> (slab %both %blah -:!>(au))

387%.n

388

389> =fe ^|(|=(a=@ +(a)))

390> (slab %read %a -:!>(fe))

391%.n

392> (slab %rite %a -:!>(fe))

393%.y

394> (slab %both %a -:!>(fe))

395%.n

396```

398---

400## `++slap`

402Untyped vase `.*`

404Compile hoon `gen` with subject `vax` using `.*`, producing a `vase` of the

405result.

406

407#### Accepts

408

409`vax` is a noun in a `vase`, and is the subject.

410

411`gen` is some `hoon`.

413#### Produces

415A `vase`.

417#### Source

419```hoon

420++ slap

421 |= [vax=vase gen=hoon] ^- vase

422 =+ gun=(~(mint ut p.vax) %noun gen)

423 [p.gun .*(q.vax q.gun)]

424```

425

426#### Examples

427

428```

429> (slap !>(b='foo') (ream '|=(a=@t [a b])'))

430[#t/<1.qgm [a=@t b=@t]> q=[[[0 6] 0 7] 0 7.303.014]]

431

432> !<($-(@t [@t @t]) (slap !>(b='foo') (ream '|=(a=@t [a b])')))

433<1|xpg [@t @t @t @t]>

434

435> (!<($-(@t [@t @t]) (slap !>(b='foo') (ream '|=(a=@t [a b])'))) 'bar')

436['bar' 'foo']

437```

439---

441## `++slog`

443Deify printf

445Prints stack trace `a` if the stack trace isn't null, then produces the other

446input. `+slog` first takes `a`, producing a gate. The gate then takes some hoon.

447

448#### Accepts

449

450`a` is a `tang`, and is the sample of `+slog`.

451

452`(slog a)` takes some `hoon`.

453

454#### Produces

455

456The result of the hoon given to `(slog a)`, with `a` printed to the terminal.

457

458#### Source

459

460```hoon

461++ slog

462 =| pri=@

463 |= a=tang ^+ same

464 ?~(a same ~>(%slog.[pri i.a] $(a t.a)))

465```

466

467#### Examples

468

469```

470foo

471> ((slog leaf+"foo" ~) (add 1 1))

4722

473```

474

475#### Discussion

476

477`slog` is intended to be put in the middle of a bunch of chained function

478calls that string a piece of data through them, so that an error message will be

479printed if there's one to print.

481---

483## `++mean`

485Crash and printf

487Ends the program and prints `a`, a tracing error message.

489#### Accepts

491`a` is a `tang`.

493#### Produces

495A crash, with `a` printed to the terminal.

496

497#### Source

498

499```hoon

500++ mean

501 |= a=tang

502 ^+ !!

503 ?~ a !!

504 ~_(i.a $(a t.a))

505```

506

507#### Examples

508

509```

510> (mean leaf+"foo" ~)

511foo

512dojo: hoon expression failed

513```

515---

517## `++road`

519Evaluate trap

521Evaluate a `trap`, producing the result if successful or else

522crashing with a trace.

524#### Accepts

526A `trap`.

528#### Produces

530A noun.

532#### Source

534```hoon

535++ road

536 |* =(trap *)

537 ^+ $:trap

538 =/ res (mule trap)

539 ?- -.res

540 %& p.res

541 %| (mean p.res)

542 ==

543```

544

545#### Examples

546

547```

548> (road |.("foo"))

549"foo"

550

551> (road |.(~|('crash!' !!)))

552'crash!'

553dojo: hoon expression failed

554```

556---

558## `++slew`

560Get axis in vase

562Get axis `axe` in vase `vax`, producing the resulting `vase` in a `unit` which is null if

563the axis cannot be retrieved.

564

565#### Accepts

566

567`axe` is an atom.

568

569`vax` is a `vase`.

571#### Produces

573A `(unit vase)`.

575#### Source

577```hoon

578++ slew

579 |= [axe=@ vax=vase] ^- (unit vase)

580 ?. |- ^- ?

581 ?: =(1 axe) &

582 ?. ?=(^ q.vax) |

583 $(axe (mas axe), q.vax .*(q.vax [0 (cap axe)]))

584 ~

585 `[(~(peek ut p.vax) %free axe) .*(q.vax [0 axe])]

586```

587

588#### Examples

589

590```

591> (slew 3 !>(['foo' 'bar']))

592[~ [#t/@t q=7.496.034]]

593

594> !<(@t (need (slew 3 !>(['foo' 'bar']))))

595'bar'

596

597> (slew 7 !>(['foo' 'bar']))

598~

599```

600

601---

602

603## `++slim`

604

605Identical to `++seer`

606

607Convert a `vise` (old `vase`) to a `vase`. Identical to [`++seer`](#seer).

608

609#### Accepts

610

611`old` is a `vise`.

613#### Produces

615A `vase`.

617#### Source

619```hoon

620++ slim

621 |= old=vise ^- vase

622 old

623```

624

625#### Examples

626

627```

628> (slim !>('foo'))

629[#t/@t q=7.303.014]

630```

632---

634## `++slit`

636Type of slam

638The `type` produced if a gate of type `gat` were slammed with a sample of type `sam`.

639

640#### Accepts

641

642`gat` is a `type`.

643

644`sam` is a `type`.

646#### Produces

648A `type`.

650#### Source

652```hoon

653++ slit

654 |= [gat=type sam=type]

655 ?> (~(nest ut (~(peek ut gat) %free 6)) & sam)

656 (~(play ut [%cell gat sam]) [%cnsg [%$ ~] [%$ 2] [%$ 3] ~])

657```

658

659#### Examples

660

661```

662> (slit -:!>(|*(a=@ [a a])) -:!>(42))

663#t/[@ud @ud]

664

665> (slit -:!>(|*(a=@ [a a])) -:!>('foo'))

666#t/[@t @t]

667```

669---

671## `++slob`

673Superficial arm

675#### Source

677```hoon

678++ slob

679 |= [cog=@tas typ=type]

680 ^- ?

681 ?+ typ |

682 [%hold *] $(typ ~(repo ut typ))

683 [%hint *] $(typ ~(repo ut typ))

684 [%core *]

685 |- ^- ?

686 ?~ q.r.q.typ |

687 ?| (~(has by q.q.n.q.r.q.typ) cog)

688 $(q.r.q.typ l.q.r.q.typ)

689 $(q.r.q.typ r.q.r.q.typ)

690 ==

691 ==

692```

694---

696## `++sloe`

698Get arms in core

700Produces a list of the arms in a core of type `typ`.

702#### Accepts

704`typ` is a type.

706#### Produces

708A `(list term)`.

710#### Source

712```hoon

713++ sloe

714 |= typ=type

715 ^- (list term)

716 ?+ typ ~

717 [%hold *] $(typ ~(repo ut typ))

718 [%hint *] $(typ ~(repo ut typ))

719 [%core *]

720 %- zing

721 %+ turn ~(tap by q.r.q.typ)

722 |= [* b=tome]

723 %+ turn ~(tap by q.b)

724 |= [a=term *]

725 a

726 ==

727```

728

729#### Examples

730

731```

732> (sloe -:!>(|=(@ 1)))

733~[%$]

734

735> =cr |%

736 ++ foo 1

737 ++ bar 2

738 ++ baz 3

739 --

740

741> (sloe -:!>(cr))

742~[%foo %baz %bar]

743

744> (sloe -:!>(42))

745~

746```

748---

750## `++slop`

752Cons two vases

754Produce the vase of a cell of vases `hed` and `tal`.

755

756#### Accepts

757

758`hed` is a `vase`.

759

760`tal` is a `vase`.

762#### Produces

764A `vase`.

766#### Source

768```hoon

769++ slop

770 |= [hed=vase tal=vase]

771 ^- vase

772 [[%cell p.hed p.tal] [q.hed q.tal]]

773```

774

775#### Examples

776

777```

778> (slop !>('foo') !>(42))

779[#t/[@t @ud] q=[7.303.014 42]]

780

781> !<([@t @ud] (slop !>('foo') !>(42)))

782['foo' 42]

783```

785---

787## `++slot`

789Got axis in vase

791Get axis `axe` in vase `vax`, returning it in a `vase`. Crashes if the axis

792cannot be retrieved.

793

794#### Accepts

795

796`axe` is an atom.

797

798`vax` is a `vase`.

800#### Produces

802A `vase`.

804#### Source

806```hoon

807++ slot

808 |= [axe=@ vax=vase] ^- vase

809 [(~(peek ut p.vax) %free axe) .*(q.vax [0 axe])]

810```

811

812#### Examples

813

814```

815> (slot 3 !>(['foo' 'bar']))

816[#t/@t q=7.496.034]

817

818> !<(@t (slot 3 !>(['foo' 'bar'])))

819'bar'

820

821> (slot 7 !>(['foo' 'bar']))

822dojo: hoon expression failed

823```

824

825---

826

827## `++slym`

828

829Slam without sample-type

830

831Slam `gat`, a gate in a `vase`, with `sam`, a `noun`. The type of `sam` is

832ignored and the type of the resulting vase is determined by the gate alone.

833

834#### Accepts

835

836`gat` is a `vase`.

838`sam` is a noun.

840#### Produces

842A `vase`.

844#### Source

846```hoon

847++ slym

848 |= [gat=vase sam=*] ^- vase

849 (slap gat(+<.q sam) [%limb %$])

850```

851

852#### Examples

853

854```

855> (slym !>(|*(a=@ux [a a])) 'foo')

856[#t/[@ux @ux] q=[7.303.014 7.303.014]]

857

858> (slym !>(|*(a=@ux [a a])) "foobar")

859[#t/[@ux @ux] q=[[102 111 111 98 97 114 0] 102 111 111 98 97 114 0]]

860```

862---

864## `++sped`

866Reconstruct type

868#### Source

870```hoon

871++ sped

872 |= vax=vase

873 ^- vase

874 :_ q.vax

875 ?@ q.vax (~(fuse ut p.vax) [%atom %$ ~])

876 ?@ -.q.vax

877 ^= typ

878 %- ~(play ut p.vax)

879 [%wtgr [%wtts [%leaf %tas -.q.vax] [%& 2]~] [%$ 1]]

880 (~(fuse ut p.vax) [%cell %noun %noun])

881```

883---

885## `++swat`

887Deferred `++slap`

889This is the same as [`++slap`](#slap) except `tap` is the subject `vase`

890encapsulated in a `trap`, and a `(trap vase)` is produced.

891

892#### Accepts

893

894`tap` is a `(trap vase)`.

896`gen` is `hoon`.

898#### Produces

900A `(trap vase)`.

902#### Source

904```hoon

905++ swat

906 |= [tap=(trap vase) gen=hoon]

907 ^- (trap vase)

908 =/ gun (~(mint ut p:$:tap) %noun gen)

909 |. ~+

910 [p.gun .*(q:$:tap q.gun)]

911```

912

913#### Examples

914

915```

916> %. 10

917 !< $-(@ @)

918 %- road

919 %+ swat

920 |.(!>(add-42=(cury add 42)))

921 (ream '|=(a=@ (add-42 a))')

92252

923```

924

925---