52a89d8 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

move task structure under accepts sections

52a89d8tinnus-napbus5 years ago

arvo/clay/tasks.md+46−46

compare with master

unifiedsplit

@@ -39,14 +39,14 @@ The focus of this document is on interacting with Clay from userspace applicatio

40# `%warp`

42−```hoon

43−[%warp wer=ship rif=riff] :: internal file req

44−```

45−

46A `%warp` `task` is for reading a subscribing to files and directories.

42A `%warp` `task` is for reading a subscribing to files and directories.

48### Accepts

44### Accepts

46+```hoon

47+[wer=ship rif=riff]

48+```

49+

50The `wer` field is the target ship. The `(unit rave)` of the [riff](@/docs/arvo/clay/data-types.md#riff-clay-request-desist) is null to cancel an existing subscription, otherwise the [rave](@/docs/arvo/clay/data-types.md#rave-clay-general-subscription-request) is tagged with one of:

52- `%sing` - Read a single file or directory.

@@ -172,14 +172,14 @@ To cancel a subscription, you just send a `%warp` with a null `(unit rave)` in t

172

173## `%info`

174

175−```hoon

176−[%info des=desk dit=nori] :: internal edit

177−```

178−

179To write or modify a file, we send Clay a `%info` `task`.

175To write or modify a file, we send Clay a `%info` `task`.

180

176

181### Accepts

177### Accepts

182

178

179+```hoon

180+[des=desk dit=nori]

181+```

182+

183The `%|` tag in the [nori](@/docs/arvo/clay/data-types.md#nori-clay-repository-action) is not currently supported and will crash with a `%labelling-not-implemented` if used, so you can focus on the `%&` part. The [soba](@/docs/arvo/clay/data-types.md#soba-clay-delta) in the `nori` is just a list of changes so you can make more than one change in one request. Its `path` is just the path to a file like `/gen/hood/hi/hoon` and the [miso](@/docs/arvo/clay/data-types.md#miso-clay-ankh-delta) is one of these types of requests:

184

185- `%del` - Delete a file.

@@ -214,14 +214,14 @@ There are four Clay `task`s relevant to mounts:

214

215## `%boat`

216

217−```hoon

218−[%boat ~]

219−```

220−

221A `%boat` `task` requests the list of existing mounts.

217A `%boat` `task` requests the list of existing mounts.

222

218

223### Accepts

219### Accepts

224

220

221+```hoon

222+~

223+```

224+

225A `%boat` `task` does not take any arguments.

226

227### Returns

@@ -240,14 +240,15 @@ The type it returns is a `%hill` `gift`, which looks like:

240

241## `%mont`

242

243−```hoon

244−[%mont pot=term bem=beam]

245−```

246

243

247A `%mont` `task` mounts the specified `beam` to the specified `term` mount point.

244A `%mont` `task` mounts the specified `beam` to the specified `term` mount point.

248

245

249### Accepts

246### Accepts

250

247

248+```hoon

249+[pot=term bem=beam]

250+```

251+

251A `beam:clay` is the following structure:

252A `beam:clay` is the following structure:

252

253

253```hoon

254```hoon

@@ -266,14 +267,14 @@ Clay does not return a `gift` in response to a `%mont` `%task`.

266

267

267## `%ogre`

268## `%ogre`

268

269

269−```hoon

270−[%ogre pot=$@(desk beam)]

271−```

272−

273A `%ogre` `task` unmounts the specified mount.

270A `%ogre` `task` unmounts the specified mount.

274

271

275### Accepts

272### Accepts

276

273

274+```hoon

275+[pot=$@(desk beam)]

276+```

277+

277It's defined in `lull.hoon` as taking `$@(desk beam)` but in fact it will only unmount the target when specified as a `term` mount name. Passing it a `desk` will incidentally work if the mount is named the same as the `desk` but otherwise it won't work. Passing it a `beam:clay` will simply not work.

278It's defined in `lull.hoon` as taking `$@(desk beam)` but in fact it will only unmount the target when specified as a `term` mount name. Passing it a `desk` will incidentally work if the mount is named the same as the `desk` but otherwise it won't work. Passing it a `beam:clay` will simply not work.

278

279

279### Returns

280### Returns

@@ -286,13 +287,13 @@ Clay does not return a `gift` in response to a `%ogre` `task`.

286

287

287## `%dirk`

288## `%dirk`

288

289

289−```hoon

290+A `%dirk` `task` commits changes in the target mount.

290−[%dirk des=desk]

291−```

292

291

293### Accepts

292### Accepts

294

293

295−A `%dirk` `task` commits changes in the target mount.

294+```hoon

295+des=desk

296+```

296

297

297It's defined in `lull.hoon` as taking a `desk` but like [%ogre](#ogre), it actually takes the name of a mount point rather than a `desk` as is specified.

298It's defined in `lull.hoon` as taking a `desk` but like [%ogre](#ogre), it actually takes the name of a mount point rather than a `desk` as is specified.

298

299

@@ -308,18 +309,16 @@ Clay does not return a `gift` in response to a `%dirk` `task`.

308

309

309## `%merg`

310## `%merg`

310

311

311−```hoon

312−$: %merg :: merge desks

313− des=desk :: target

314− her=@p dem=desk cas=case :: source

315− how=germ :: method

316−== ::

317−```

318−

319A `%merg` `task` will merge the specified source `desk` into the target local `desk`.

312A `%merg` `task` will merge the specified source `desk` into the target local `desk`.

320

313

321### Accepts

314### Accepts

322

315

316+```hoon

317+$: des=desk :: target

318+ her=@p dem=desk cas=case :: source

319+ how=germ :: method

320+==

321+```

323The `germ` specifies the merge strategy. You can refer to the [Strategies](@/docs/arvo/clay/using.md#strategies) section of the [Using Clay](@/docs/arvo/clay/using.md) document for details of each `germ`.

322The `germ` specifies the merge strategy. You can refer to the [Strategies](@/docs/arvo/clay/using.md#strategies) section of the [Using Clay](@/docs/arvo/clay/using.md) document for details of each `germ`.

324

323

325If you're merging into a new `desk` you must use `%init`, all other strategies will fail. If the desk already exists, you cannot use `%init`. Otherwise, you're free to use whichever you'd like.

324If you're merging into a new `desk` you must use `%init`, all other strategies will fail. If the desk already exists, you cannot use `%init`. Otherwise, you're free to use whichever you'd like.

@@ -393,16 +392,16 @@ We'll look at each of these in turn.

393

392

394## `%perm`

393## `%perm`

395

394

396−```hoon

397−[%perm des=desk pax=path rit=rite] :: change permissions

398−```

399−

400A `%perm` `task` sets permissions for the target file or directory.

395A `%perm` `task` sets permissions for the target file or directory.

401

396

402Note this will replace existing permissions rather than add to them, so if you want to add a ship to an existing whitelist or whatever you'll have to first read the existing permissions, add the ship, then send the whole lot back.

397Note this will replace existing permissions rather than add to them, so if you want to add a ship to an existing whitelist or whatever you'll have to first read the existing permissions, add the ship, then send the whole lot back.

403

398

404### Accepts

399### Accepts

405

400

401+```hoon

402+[des=desk pax=path rit=rite]

403+```

404+

406The `pax` path is the file or directory whose permissions you want to change, and the `rite` is this structure:

405The `pax` path is the file or directory whose permissions you want to change, and the `rite` is this structure:

407

406

408```hoon

407```hoon

@@ -436,14 +435,14 @@ Clay does not return a `gift` in response to a `%perm` `task`.

436

435

437## `%cred`

436## `%cred`

438

437

439−```hoon

440−[%cred nom=@ta cew=crew] :: set permission group

441−```

442−

443This simply creates a permission group.

438This simply creates a permission group.

444

439

445### Accepts

440### Accepts

446

441

442+```hoon

443+[nom=@ta cew=crew]

444+```

445+

447The `nom` is a name for the group and the `crew` is just a `(set ship)`:

446The `nom` is a name for the group and the `crew` is just a `(set ship)`:

448

447

449```hoon

448```hoon

@@ -460,13 +459,14 @@ Clay does not return a `gift` in response to a `%cred` `task`.

460

459

461## `%crew`

460## `%crew`

462

461

463−```hoon

464−[%crew ~] :: permission groups

465−```

466This retrieves all permission groups.

462This retrieves all permission groups.

467

463

468### Accepts

464### Accepts

469

465

466+```hoon

467+~

468+```

469+

470A `%crew` `task` takes no arguments.

471

472### Returns

@@ -485,14 +485,14 @@ The `cez` is just a map from group name to `crew` which is just a `(set ship)`.

485

486## `%crow`

487

488−```hoon

489−[%crow nom=@ta] :: group usage

490−```

491−

492A `%crow` `task` retrieves all files and directories in all `desk`s which have permissions set for the group in question. It will not return inherited permissions, only those explicitly set.

488A `%crow` `task` retrieves all files and directories in all `desk`s which have permissions set for the group in question. It will not return inherited permissions, only those explicitly set.

493

489

494### Accepts

490### Accepts

495

491

492+```hoon

493+nom=@ta

494+```

495+

496The `nom` is the name of a `crew`.

497

498### Returns