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

git.iko.soy/urbit.org

on 4fdc19d help sign in

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

723 lines 14 kB history raw

1+++

2title = "4n: Virtualization"

3weight = 41

4template = "doc.html"

5+++

7## `++mack`

9Nock subject to unit

11Accepts a nock subject-formula cell and wraps it into a `unit`.

12`fol` is pure nock, meaning that nock `11` operations result in a block,

13producing a `~`.

15#### Accepts

17`sub` is a subject noun.

19`fol` is a formula noun, which is generally a `nock`.

21#### Produces

23The `unit` of a noun.

25#### Source

27```hoon

28++ mack

29 |= [sub=* fol=*]

30 ^- (unit)

31 =/ ton (mink [sub fol] |~(^ ~))

32 ?.(?=(%0 -.ton) ~ `product.ton)

33```

35#### Examples

37```

38> (mack [[1 2 3] [0 1]])

39[~ [1 2 3]]

41> (mack [41 4 0 1])

42[~ 42]

44> (mack [4 0 4])

45~

47> (mack [[[0 2] [1 3]] 4 4 4 4 0 5])

48[~ 6]

50> ;;((unit @tas) (mack [[1 %yes %no] 6 [0 2] [0 6] 0 7]))

51[~ %no]

52```

54---

56## `++mink`

58Mock interpreter

60Bottom-level mock (virtual nock) interpreter. Produces a

61`tone`, a nock computation result. If nock 12 is invoked, `scry`

62computes on the subject and produces a `(unit (unit))` result. An empty

63result becomes a `%1` `tone`, indicating a block.

65#### Accepts

67`subject` is the subject as a noun.

69`formula` is the formula as a noun.

71`scry` is an `%iron` gate invoked with nock operator 12.

73#### Produces

75A `tone`.

77#### Source

79```hoon

80++ mink !.

81 ~/ %mink

82 |= $: [subject=* formula=*]

83 scry=$-(^ (unit (unit)))

84 ==

85 =| trace=(list [@ta *])

86 |^ ^- tone

87 ?+ formula [%2 trace]

88 [^ *]

89 =/ head $(formula -.formula)

90 ?. ?=(%0 -.head) head

91 =/ tail $(formula +.formula)

92 ?. ?=(%0 -.tail) tail

93 [%0 product.head product.tail]

94 ::

95 [%0 axis=@]

96 =/ part (frag axis.formula subject)

97 ?~ part [%2 trace]

98 [%0 u.part]

99 ::

100 [%1 constant=*]

101 [%0 constant.formula]

102 ::

103 [%2 subject=* formula=*]

104 =/ subject $(formula subject.formula)

105 ?. ?=(%0 -.subject) subject

106 =/ formula $(formula formula.formula)

107 ?. ?=(%0 -.formula) formula

108 %= $

109 subject product.subject

110 formula product.formula

111 ==

112 ::

113 [%3 argument=*]

114 =/ argument $(formula argument.formula)

115 ?. ?=(%0 -.argument) argument

116 [%0 .?(product.argument)]

117 ::

118 [%4 argument=*]

119 =/ argument $(formula argument.formula)

120 ?. ?=(%0 -.argument) argument

121 ?^ product.argument [%2 trace]

122 [%0 .+(product.argument)]

123 ::

124 [%5 a=* b=*]

125 =/ a $(formula a.formula)

126 ?. ?=(%0 -.a) a

127 =/ b $(formula b.formula)

128 ?. ?=(%0 -.b) b

129 [%0 =(product.a product.b)]

130 ::

131 [%6 test=* yes=* no=*]

132 =/ result $(formula test.formula)

133 ?. ?=(%0 -.result) result

134 ?+ product.result

135 [%2 trace]

136 %& $(formula yes.formula)

137 %| $(formula no.formula)

138 ==

139 ::

140 [%7 subject=* next=*]

141 =/ subject $(formula subject.formula)

142 ?. ?=(%0 -.subject) subject

143 %= $

144 subject product.subject

145 formula next.formula

146 ==

147 ::

148 [%8 head=* next=*]

149 =/ head $(formula head.formula)

150 ?. ?=(%0 -.head) head

151 %= $

152 subject [product.head subject]

153 formula next.formula

154 ==

155 ::

156 [%9 axis=@ core=*]

157 =/ core $(formula core.formula)

158 ?. ?=(%0 -.core) core

159 =/ arm (frag axis.formula product.core)

160 ?~ arm [%2 trace]

161 %= $

162 subject product.core

163 formula u.arm

164 ==

165 ::

166 [%10 [axis=@ value=*] target=*]

167 ?: =(0 axis.formula) [%2 trace]

168 =/ target $(formula target.formula)

169 ?. ?=(%0 -.target) target

170 =/ value $(formula value.formula)

171 ?. ?=(%0 -.value) value

172 =/ mutant=(unit *)

173 (edit axis.formula product.target product.value)

174 ?~ mutant [%2 trace]

175 [%0 u.mutant]

176 ::

177 [%11 tag=@ next=*]

178 =/ next $(formula next.formula)

179 ?. ?=(%0 -.next) next

180 :- %0

181 .* subject

182 [11 tag.formula 1 product.next]

183 ::

184 [%11 [tag=@ clue=*] next=*]

185 =/ clue $(formula clue.formula)

186 ?. ?=(%0 -.clue) clue

187 =/ next

188 =? trace

189 ?=(?(%hunk %hand %lose %mean %spot) tag.formula)

190 [[tag.formula product.clue] trace]

191 $(formula next.formula)

192 ?. ?=(%0 -.next) next

193 :- %0

194 .* subject

195 [11 [tag.formula 1 product.clue] 1 product.next]

196 ::

197 [%12 ref=* path=*]

198 =/ ref $(formula ref.formula)

199 ?. ?=(%0 -.ref) ref

200 =/ path $(formula path.formula)

201 ?. ?=(%0 -.path) path

202 =/ result (scry product.ref product.path)

203 ?~ result

204 [%1 product.path]

205 ?~ u.result

206 [%2 [%hunk product.ref product.path] trace]

207 [%0 u.u.result]

208 ==

209 ::

210 ++ frag

211 |= [axis=@ noun=*]

212 ^- (unit)

213 ?: =(0 axis) ~

214 |- ^- (unit)

215 ?: =(1 axis) `noun

216 ?@ noun ~

217 =/ pick (cap axis)

218 %= $

219 axis (mas axis)

220 noun ?-(pick %2 -.noun, %3 +.noun)

221 ==

222 ::

223 ++ edit

224 |= [axis=@ target=* value=*]

225 ^- (unit)

226 ?: =(1 axis) `value

227 ?@ target ~

228 =/ pick (cap axis)

229 =/ mutant

230 %= $

231 axis (mas axis)

232 target ?-(pick %2 -.target, %3 +.target)

233 ==

234 ?~ mutant ~

235 ?- pick

236 %2 `[u.mutant +.target]

237 %3 `[-.target u.mutant]

238 ==

239 --

240```

241

242#### Examples

243

244```

245> (mink [20 [4 0 1]] ,~)

246[%0 product=21]

247

248> (mink [[[4 5] [6 14 15]] [0 7]] ,~)

249[%0 product=[14 15]]

250

251> (mink [42 12 [0 1] [1 73]] |=(a=^ ``(add (,[@ @] a))))

252[%0 product=115]

253

254> (mink [0 12 [1 0] [1 0]] |=(* ~))

255[%1 block=0]

256

257> (mink [42 0 2] ,~)

258[%2 trace=~]

259```

260

261---

262

263## `++mock`

264

265Compute formula on subject with hint

266

267Produces a `toon`, which is either a sucessful, blocked, or

268crashed result. If nock 11 is invoked, `gul` computes on the subject and

269produces a `(unit (unit))` result. An empty result becomes a `%1` `tune`,

270indicating a block.

271

272#### Accepts

273

274`sub` is the subject as a noun.

275

276`fol` is the formula as a noun.

277

278`gul` is an %iron gate invoked with nock operator 11.

279

280#### Produces

281

282The `unit` of a noun.

283

284#### Source

285

286```hoon

287++ mock

288 |= [[sub=* fol=*] gul=$-(^ (unit (unit)))]

289 (mook (mink [sub fol] gul))

290```

291

292#### Examples

293

294```

295> (mock [5 4 0 1] ,~)

296[%0 p=6]

297

298> (mock [0 12 [0 1] [0 1]] |=(* ``999))

299[%0 p=999]

300

301> (mock [42 12 [0 1] [0 1]] |=(* ~))

302[%1 p=42]

303

304> (mock [42 0 2] ,~)

305[%2 p=~]

306```

307

308---

309

310## `++mook`

311

312Intelligently render crash annotation

313

314Converts a `%2` `tone` nock stack trace to a list of `tank`. Each may be a

315`tank`, `cord`, `spot`, or trapped `tank`.

316

317#### Accepts

318

319`ton` is a `tone`.

321#### Produces

323A `toon`.

325#### Source

327```hoon

328++ mook

329 |= ton=tone

330 ^- toon

331 ?. ?=([%2 *] ton)

332 ton

333 |^ [%2 (turn skip rend)]

334 ::

335 ++ skip

336 ^+ trace.ton

337 =/ yel (lent trace.ton)

338 ?. (gth yel 1.024) trace.ton

339 %+ weld

340 (scag 512 trace.ton)

341 ^+ trace.ton

342 :_ (slag (sub yel 512) trace.ton)

343 :- %lose

344 (crip "[skipped {(scow %ud (sub yel 1.024))} frames]")

345 ::

346 :: +rend: raw stack frame to tank

347 ::

348 :: $% [%hunk ref=* path] :: failed scry ([~ ~])

349 :: [%lose cord] :: skipped frames

350 :: [%hand *] :: mug any

351 :: [%mean $@(cord (trap tank))] :: ~_ et al

352 :: [%spot spot] :: source location

353 :: ==

354 ::

355 ++ rend

356 |= [tag=@ta dat=*]

357 ^- tank

358 ?+ tag

359 ::

360 leaf+"mook.{(rip 3 tag)}"

361 ::

362 %hunk

363 ?@ dat leaf+"mook.hunk"

364 =/ sof=(unit path) ((soft path) +.dat)

365 ?~ sof leaf+"mook.hunk"

366 (smyt u.sof)

367 ::

368 %lose

369 ?^ dat leaf+"mook.lose"

370 leaf+(rip 3 dat)

371 ::

372 %hand

373 leaf+(scow %p (mug dat))

374 ::

375 %mean

376 ?@ dat leaf+(rip 3 dat)

377 =/ mac (mack dat -.dat)

378 ?~ mac leaf+"####"

379 =/ sof ((soft tank) u.mac)

380 ?~ sof leaf+"mook.mean"

381 u.sof

382 ::

383 %spot

384 =/ sof=(unit spot) ((soft spot) dat)

385 ?~ sof leaf+"mook.spot"

386 :+ %rose [":" ~ ~]

387 :~ (smyt p.u.sof)

388 =* l p.q.u.sof

389 =* r q.q.u.sof

390 =/ ud |=(a=@u (scow %ud a))

391 leaf+"<[{(ud p.l)} {(ud q.l)}].[{(ud p.r)} {(ud q.r)}]>"

392 ==

393 ==

394 --

395```

396

397#### Examples

398

399```

400> (mook [%0 5 4 5 1])

401[%0 p=[5 4 5 1]]

402

403> (mook [%2 ~[[%hunk %rose ["<" "," ">"] ~[[%leaf "err"]]]]])

404[%2 p=~[[%leaf p="mook.hunk"]]]

405

406> (mook [%2 ~[[%mean |.(>(add 5 6)<)]]])

407[%2 p=~[[%leaf p="11"]]]

408

409> (mook [%2 ~[[%spot /b/repl [1 1]^[1 2]] [%mean |.(!!)]]])

410[ %2

411 p

412 ~[

413 [ %rose

414 p=[p=":" q="" r=""]

415 q

416 [ i

417 [ %rose

418 p=[p="/" q="/" r=""]

419 q=[i=[%leaf p="b"] t=[i=[%leaf p="repl"] t=~]]

420 ]

421 t=[i=[%leaf p="<[1 1].[1 2]>"] t=~]

422 ]

423 ]

424 [%leaf p="####"]

425 ]

426]

427```

428

429---

430

431## `++mole`

432

433Typed unitary virtual

434

435Kicks a `trap`, producing its result in a `unit` if successful, or a null `unit`

436if it crashed. Unitized version of [`++mule`](#mule).

437

438#### Accepts

439

440`tap` is a `trap`.

441

442#### Produces

443

444A `(unit *)`, where the `*` will be the type produced by the expression.

445

446#### Source

447

448```hoon

449++ mole

450 ~/ %mole

451 |* tap=(trap)

452 ^- (unit _$:tap)

453 =/ mur (mure tap)

454 ?~(mur ~ `$:tap)

455```

456

457#### Examples

458

459```

460> (mole |.(`@t`(add 50 47)))

461[~ 'a']

462

463> (mole |.(~|('Error!' !!)))

464~

465```

466

467---

468

469## `++mong`

470

471Slam gate with sample

472

473Produces a `toon` computation result from slamming `gat` with

474`sam`, using `gul` to compute or block on nock 11 when applicable.

475

476#### Accepts

477

478`gat` is a noun that is generally a `gate`.

479

480`sam` is a sample noun.

481

482`gul` is an `%iron` gate invoked with nock operator 11.

484#### Produces

486A `toon`.

488#### Source

490```hoon

491++ mong

492 |= [[gat=* sam=*] gul=$-(^ (unit (unit)))]

493 ^- toon

494 ?. ?=([* ^] gat) [%2 ~]

495 (mock [gat(+< sam) %9 2 %0 1] gul)

496```

497

498#### Examples

499

500```

501> (mong [|=(@ 20) ~] ,~)

502[%0 p=20]

503

504> (mong [|=(@ !!) ~] ,~)

505[%2 p=~]

506

507> (mong [|=(a=@ (add 20 a)) ~] ,~)

508[%0 p=20]

509

510> (mong [|=(a=[@ @] (add 20 -.a)) ~] ,~)

511[%2 p=~]

512

513> (mong [|=(a=[@ @] (add 20 -.a)) [4 6]] ,~)

514[%0 p=24]

515

516> (mong [|=(a=@ .^(* a)) 99] |=(^ ``+<))

517[%0 p=[[140 1.853.189.998] 99]]

518

519> (mong [|=(a=@ .^(@ a)) 99] |=([* a=*] ``+((,@ a))))

520[%0 p=100]

521```

523---

525## `++mule`

527Typed virtual

529Kicks a `trap`, producing its results or any errors that occur along

530the way. Used to lazily compute stack traces.

531

532#### Accepts

533

534`tap` is a `trap`, generally producing a list of `tank`s.

535

536#### Produces

537

538An `(each * (list tank))` - `%.y` indicates success and `%.n` indicates a crash.

539

540#### Source

541

542```hoon

543++ mule

544 ~/ %mule

545 |* tap=(trap)

546 =/ mud (mute tap)

547 ?- -.mud

548 %& [%& p=$:tap]

549 %| [%| p=p.mud]

550 ==

551```

552

553#### Examples

554

555```

556> (mule |.((add 1 1)))

557[%.y p=2]

558

559> (mule |.(~|(%error !!)))

560[%.n p=~[[%leaf p="%error"]]]

561```

562

563---

564

565## `++mure`

566

567Untyped unitary virtual

568

569Kicks a `trap`, producing its results in a `unit` which is null if it crashed.

570The result is just a noun, no type information is preserved.

572#### Accepts

574A `trap`.

576#### Produces

578A `(unit *)`.

580#### Source

582```hoon

583++ mure

584 |= tap=(trap)

585 ^- (unit)

586 =/ ton (mink [tap %9 2 %0 1] |=((pair) ``.*(~ [%12 1+p 1+q])))

587 ?.(?=(%0 -.ton) ~ `product.ton)

588```

589

590#### Examples

591

592```

593> (mure |.(~|(%error !!)))

594~

595

596> (mure |.((add 1 1)))

597[~ 2]

598

599> (mure |.('foo'))

600[~ 7.303.014]

601

602> ((unit @t) (mure |.('foo')))

603[~ 'foo']

604```

606---

608## `++mute`

610Untyped virtual

612Kicks a `trap`, producing its result as a noun or the tanks of any error that

613occurs. Similar to [`++mule`](#mule), but preserves no type information.

614

615#### Accepts

616

617`tap` is a `trap`.

618

619#### Produces

620

621A `(each * (list tank))`, where `%.y` indicates success and `%.n` indicates

622failure.

623

624#### Source

625

626```hoon

627++ mute

628 |= tap=(trap)

629 ^- (each * (list tank))

630 =/ ton (mock [tap %9 2 %0 1] |=((pair) ``.*(~ [%12 1+p 1+q])))

631 ?- -.ton

632 %0 [%& p.ton]

633 ::

634 %1 =/ sof=(unit path) ((soft path) p.ton)

635 [%| ?~(sof leaf+"mute.hunk" (smyt u.sof)) ~]

636 ::

637 %2 [%| p.ton]

638 ==

639```

640

641#### Examples

642

643```

644> (mute |.(leaf+"hello"))

645[%.y p=[1.717.658.988 104 101 108 108 111 0]]

646

647> (mute |.(!!))

648[%.n p=~]

649

650> (mute |.(~|(%error !!)))

651[%.n p=~[[%leaf p="%error"]]]

652

653> (mute |.((cat 3 'foo' 'bar')))

654[%.y p=125.762.588.864.358]

655```

656

657---

658

659## `++slum`

660

661Slam a gate on a sample using raw nock, untyped

662

663Slam `gat` with `sam`. Uses a raw `.*` nock expression internally and does not

664preserve type information for the result. This will crash if evaluation crashes.

665

666#### Examples

667

668```

669> (slum |=([a=@ b=@] (add a b)) [7 9])

67016

671

672> (slum (cury cat 3) ['foo' 'bar'])

673125.762.588.864.358

674

675> (@t (slum (cury cat 3) ['foo' 'bar']))

676'foobar'

677

678> (slum |=(* !!) 42)

679dojo: hoon expression failed

680```

682---

684## `++soft`

686Virtual clam

688Clam (mold) noun `fud` with `mold` `han`, producing a `unit` of the result. The

689`unit` is null if clamming failed. This is curried, so the soft-clamming gate can

690be stored and called repeatedly.

691

692#### Accepts

693

694`han` is a `mold`.

695

696`fud` is a noun.

697

698#### Produces

699

700A `(unit *)`, where the `*` will be the type produced by the mold.

701

702#### Source

703

704```hoon

705++ soft

706 |* han=$-(* *)

707 |=(fud=* (mole |.((han fud))))

708```

709

710#### Examples

711

712```

713> ((soft @t) 97)

714[~ 'a']

715

716> ((soft @t) [1 2])

717~

718

719> ((soft ,[@ux @ux]) ['a' 'b'])

720[~ [0x61 0x62]]

721```

722

723---