ed71dae · urbit.org · git.iko.soy

git.iko.soy/urbit.org

change send-task thread to |pass in examples

ed71daetinnus-napbus5 years ago

arvo/clay/examples.md+31−50

@@ -38,26 +38,7 @@ template = "doc.html"

39This document contains a number of examples of interacting with Clay using its various `task`s. Sections correspond to the general details in the [API Reference](@/docs/arvo/clay/tasks.md) document.

41−Most examples use one of these two threads which you can save to the `ted` directory of your `%home` `desk`:

41+Most examples will either use `|pass` to just send a `task` or the following thread to send a `task` and take the resulting `gift`. You can save the following thread to the `ted` directory of your `%home` `desk`:

42−

43−`send-task.hoon`

44−

45−```hoon

46−/- spider

47−/+ strandio

48−=, strand=strand:spider

49−^- thread:spider

50−|= arg=vase

51−=/ m (strand ,vase)

52−^- form:m

53−=/ uarg !< (unit task:clay) arg

54−?~ uarg

55− (strand-fail:strand %no-arg ~)

56−=/ =task:clay u.uarg

57−=/ =card:agent:gall [%pass /foo %arvo %c task]

58−;< ~ bind:m (send-raw-card:strandio card)

59−(pure:m !>(~))

60−```

62`send-task-take-gift.hoon`

43`send-task-take-gift.hoon`

@@ -376,10 +357,10 @@ See the [Write and Modify](@/docs/arvo/clay/tasks.md#write-and-modify) section o

376

357

377Here we'll look at adding a file by sending Clay a `%info` `task` containing a `%ins` `miso`.

358Here we'll look at adding a file by sending Clay a `%info` `task` containing a `%ins` `miso`.

378

359

379−Using the `send-task.hoon` thread, let's try adding a `foo.txt` file with 'foo' as its contents:

360+Let's try adding a `foo.txt` file with 'foo' as its contents:

380

361

381```

362```

382−> -send-task [%info %home %& [/foo/txt %ins %txt !>(~['foo'])]~]

363+> |pass [%c [%info %home %& [/foo/txt %ins %txt !>(~['foo'])]~]]

383+ /~zod/home/5/foo/txt

364+ /~zod/home/5/foo/txt

384```

365```

385

366

@@ -395,10 +376,10 @@ Here's a breakdown of the `task` we sent:

395

376

396Here we'll look at deleting a file by sending Clay a `%info` `task` containing a `%del` `miso`.

377Here we'll look at deleting a file by sending Clay a `%info` `task` containing a `%del` `miso`.

397

378

398−Using the `send-task.hoon` thread, let's try deleting the `foo.txt` file created in the [previous example](#ins):

379+Let's try deleting the `foo.txt` file created in the [previous example](#ins):

399

380

400```

381```

401−> -send-task [%info %home %& [/foo/txt %del ~]~]

382+> |pass [%c [%info %home %& [/foo/txt %del ~]~]]

402- /~zod/home/6/foo/txt

383- /~zod/home/6/foo/txt

403```

384```

404

385

@@ -472,10 +453,10 @@ Using the `send-task-take-gift.hoon` thread, let's make such a request:

472

453

473Here we'll look at mounting `desk`s, directories and files to unix by sending Clay a `%mont` `task`.

454Here we'll look at mounting `desk`s, directories and files to unix by sending Clay a `%mont` `task`.

474

455

475−Using the `send-task.hoon` thread, let's first try mounting our `%kids` desk:

456+Let's first try mounting our `%kids` desk:

476

457

477```

458```

478−> -send-task [%mont %kids [our %kids da+now] /]

459+> |pass [%c [%mont %kids [our %kids da+now] /]]

479```

460```

480

461

481If you look in your pier, you should now see a `kids` folder which contains the contents of that `desk`.

462If you look in your pier, you should now see a `kids` folder which contains the contents of that `desk`.

@@ -493,7 +474,7 @@ The cez is just a map from group name to crew

493Note the mount point doesn't need to match a `desk`, file or directory. We can also do:

474Note the mount point doesn't need to match a `desk`, file or directory. We can also do:

494

475

495```

476```

496−> -send-task [%mont %wibbly-wobbly [our %home da+now] /]

477+> |pass [%c [%mont %wibbly-wobbly [our %home da+now] /]]

497```

478```

498

479

499And you'll now see that there's a `wibbly-wobbly` folder with the contents of the `%home` `desk`. You'll also notice we can mount the same file or directory more than once. There's no problem having `%home` mounted to both `home` and `wibbly-wobbly`. The only requirement is that their mount points be unique.

480And you'll now see that there's a `wibbly-wobbly` folder with the contents of the `%home` `desk`. You'll also notice we can mount the same file or directory more than once. There's no problem having `%home` mounted to both `home` and `wibbly-wobbly`. The only requirement is that their mount points be unique.

@@ -501,8 +482,8 @@ And you'll now see that there's a `wibbly-wobbly` folder with the contents of th

501Let's try mounting a subdirectory and a single folder:

482Let's try mounting a subdirectory and a single folder:

502

483

503```

484```

504−> -send-task [%mont %gen [our %home da+now] /gen]

485+> |pass [%c [%mont %gen [our %home da+now] /gen]]

505−> -send-task [%mont %hi [our %home da+now] /gen/hood/hi]

486+> |pass [%c [%mont %hi [our %home da+now] /gen/hood/hi]]

506```

487```

507

488

508If you look in your pier you'll now see a `gen` folder with the contents of `/gen` and a `hi.hoon` file by itself. Notice how the file extension has been automatically added.

489If you look in your pier you'll now see a `gen` folder with the contents of `/gen` and a `hi.hoon` file by itself. Notice how the file extension has been automatically added.

@@ -511,28 +492,28 @@ If you look in your pier you'll now see a `gen` folder with the contents of `/ge

511

492

512Here we'll look at unmounting `desk`s, directories and files by sending Clay a `%ogre` `task`.

493Here we'll look at unmounting `desk`s, directories and files by sending Clay a `%ogre` `task`.

513

494

514−Using the `send-task.hoon` thread, let's unmount what we mounted in the [%mont](#mont) section. First we'll unmount the `%kids` desk:

495+Let's unmount what we mounted in the [%mont](#mont) section. First we'll unmount the `%kids` desk:

515

496

516```

497```

517−-send-task [%ogre %kids]

498+|pass [%c [%ogre %kids]]

518```

499```

519

500

520Our custom mount point `%wibbly-wobbly`:

501Our custom mount point `%wibbly-wobbly`:

521

502

522```

503```

523−-send-task [%ogre %wibbly-wobbly]

504+|pass [%c [%ogre %wibbly-wobbly]]

524```

505```

525

506

526And the single `hi.hoon` we previously mounted by specifying its mount point `%hi`:

507And the single `hi.hoon` we previously mounted by specifying its mount point `%hi`:

527

508

528```

509```

529−-send-task [%ogre %hi]

510+|pass [%c [%ogre %hi]]

530```

511```

531

512

532If we specify a non-existent mount point it will fail with an error printed to the dojo like:

513If we specify a non-existent mount point it will fail with an error printed to the dojo like:

533

514

534```

515```

535−> -send-task [%ogre %kids]

516+> |pass [%c [%ogre %kids]]

536[%not-mounted %kids]

517[%not-mounted %kids]

537```

518```

538

519

@@ -542,10 +523,10 @@ If we give it an unmounted `beam` it will not print an error but still won't wor

542

523

543Here we'll look at committing changed files by sending Clay a `%dirk` `task`.

524Here we'll look at committing changed files by sending Clay a `%dirk` `task`.

544

525

545−With your `%home` `desk` mounted, try adding a file and, using the `send-task.hoon` thread, send a `%dirk` to commit the change:

526+With your `%home` `desk` mounted, try adding a file and send a `%dirk` to commit the change:

546

527

547```

528```

548−> -send-task [%dirk %home]

529+> |pass [%c [%dirk %home]]

549+ /~zod/home/12/foo/txt

530+ /~zod/home/12/foo/txt

550```

531```

551

532

@@ -636,10 +617,10 @@ See the [Permissions](@/docs/arvo/clay/tasks.md#permissions) section of the [API

636

617

637Here we'll look at setting permissions by sending Clay a `%perm` `task`.

618Here we'll look at setting permissions by sending Clay a `%perm` `task`.

638

619

639−First, using the `send-task.hoon` thread, let's try allow `~nes` to read `/gen/hood/hi/hoon`:

620+First, let's allow `~nes` to read `/gen/hood/hi/hoon`:

640

621

641```

622```

642−> -send-task [%perm %home /gen/hood/hi/hoon %r ~ %white (sy [%.y ~nes]~)]

623+> |pass [%c [%perm %home /gen/hood/hi/hoon %r ~ %white (sy [%.y ~nes]~)]]

643```

624```

644

625

645...and we'll do a `%p` scry to see that the permission was set:

626...and we'll do a `%p` scry to see that the permission was set:

@@ -652,7 +633,7 @@ First, using the `send-task.hoon` thread, let's try allow `~nes` to read `/gen/h

652You can see that `~nes` is now in the read whitelist. Next, let's try a write permission:

633You can see that `~nes` is now in the read whitelist. Next, let's try a write permission:

653

634

654```

635```

655−> -send-task [%perm %home /ted %w ~ %white (sy [%.y ~nes]~)]

636+> |pass [%c [%perm %home /ted %w ~ %white (sy [%.y ~nes]~)]]

656```

637```

657

638

658You can see `~nes` can now write to `/ted`:

639You can see `~nes` can now write to `/ted`:

@@ -674,7 +655,7 @@ Since we've set it for the whole `/ted` directory, if we check a file inside it

674Now let's try setting both read and write permissions:

655Now let's try setting both read and write permissions:

675

656

676```

657```

677−> -send-task [%perm %home /gen/help/hoon %rw `[%black (sy [%.y ~nes]~)] `[%white (sy [%.y ~nes]~)]]

658+> |pass [%c [%perm %home /gen/help/hoon %rw `[%black (sy [%.y ~nes]~)] `[%white (sy [%.y ~nes]~)]]]

678```

659```

679

660

680```

661```

@@ -687,7 +668,7 @@ Lastly, let's look at deleting a permission rule we've previously set. To do tha

687For example, to remove a read permission (or write if you specify `%w`):

668For example, to remove a read permission (or write if you specify `%w`):

688

669

689```

670```

690−> -send-task [%perm %home /gen/help/hoon %r ~]

671+> |pass [%c [%perm %home /gen/help/hoon %r ~]]

691```

672```

692

673

693```

674```

@@ -698,7 +679,7 @@ For example, to remove a read permission (or write if you specify `%w`):

698...and to remove both read and write at the same time:

679...and to remove both read and write at the same time:

699

680

700```

681```

701−> -send-task [%perm %home /gen/help/hoon %rw ~ ~]

682+> |pass [%c [%perm %home /gen/help/hoon %rw ~ ~]]

702```

683```

703

684

704```

685```

@@ -716,10 +697,10 @@ Here's a breakdown of a `%perm` task:

716

697

717Here we'll look at creating a permission group by sending Clay a `%cred` `task`.

698Here we'll look at creating a permission group by sending Clay a `%cred` `task`.

718

699

719−Using the `send-task.hoon` thread, try:

700+Let's create a group called `'foo'` with a few ships:

720

701

721```

702```

722−-send-task [%crew 'foo' (sy ~[~zod ~nec ~bud ~wes ~sev])]

703+|pass [%c [%crew 'foo' (sy ~[~zod ~nec ~bud ~wes ~sev])]]

723```

704```

724

705

725We'll check it with the next kind of `task`: [%crew](#crew).

706We'll check it with the next kind of `task`: [%crew](#crew).

@@ -739,11 +720,11 @@ Let's check, using the `send-task-take-gift.hoon` thread, for the permission gro

739

720

740Here we'll look at retrieving a list of all files and directories in all `desk`s which have permissions set for a group by sending Clay a `%crow` `task` and receiving a `%croz` `gift` in response.

721Here we'll look at retrieving a list of all files and directories in all `desk`s which have permissions set for a group by sending Clay a `%crow` `task` and receiving a `%croz` `gift` in response.

741

722

742−First we'll set a couple of permissions for the `foo` group we created in the [%cred](#cred) section using the `send-task.hoon` thread:

723+First we'll set a couple of permissions for the `foo` group we created in the [%cred](#cred) section:

743

724

744```

725```

745−> -send-task [%perm %home /gen/hood/hi/hoon %w ~ %white (sy [%.n 'foo']~)]

726+> |pass [%c [%perm %home /gen/hood/hi/hoon %w ~ %white (sy [%.n 'foo']~)]]

746−> -send-task [%perm %home /ted %w ~ %white (sy [%.n 'foo']~)]

727+> |pass [%c [%perm %home /ted %w ~ %white (sy [%.n 'foo']~)]]

747```

728```

748

729

749Notice we use a `%.n` in the `whom` to indicate a group rather than the `%.y` of a ship.

730Notice we use a `%.n` in the `whom` to indicate a group rather than the `%.y` of a ship.

@@ -777,10 +758,10 @@ Here we'll look at reading files on a foreign ship by sending Clay a `%warp` `ta

777

758

778We'll use a fake ~nes as the the foreign ship and a fake ~zod as the local ship.

759We'll use a fake ~nes as the the foreign ship and a fake ~zod as the local ship.

779

760

780−First we'll set permissions on the foreign ship. Create a file called `foo.txt` in the `%home` of ~nes. Using the `send-task.hoon` thread, send a `%perm` request to allow ~zod to read and write the file:

761+First we'll set permissions on the foreign ship. Create a file called `foo.txt` in the `%home` of ~nes, then send a `%perm` request to allow ~zod to read and write the file:

781

762

782```

763```

783−> -send-task [%perm %home /foo/txt %rw `[%white (sy [%.y ~zod]~)] `[%white (sy [%.y ~zod]~)]]

764+> |pass [%c [%perm %home /foo/txt %rw `[%white (sy [%.y ~zod]~)] `[%white (sy [%.y ~zod]~)]]]

784```

765```

785

766

786If we scry the file for its permissions with a `%p` `care`, we'll see ~zod is now whitelisted:

767If we scry the file for its permissions with a `%p` `care`, we'll see ~zod is now whitelisted:

@@ -823,7 +804,7 @@ As you can see, we've received a `%writ` containing the requested data just as w

823If we send a `%d` request however, it will crash:

804If we send a `%d` request however, it will crash:

824

805

825```

806```

826−> -send-receive-task [%warp ~nes %home ~ %sing %d da+now /foo/txt]

807+> -send-task-take-gift [%warp ~nes %home ~ %sing %d da+now /foo/txt]

827call: failed

808call: failed

828/sys/vane/clay/hoon:<[4.085 3].[4.314 5]>

809/sys/vane/clay/hoon:<[4.085 3].[4.314 5]>

829...

810...