c2f44cf · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

using revisions

c2f44cfRobert8 years ago

docs/using/admin.umd+6−5

compare with master

unifiedsplit

@@ -74,7 +74,7 @@ line) and the record (everything above that). The record is shared; all

74the output from all the apps in your command set appears in it. The

75prompt is multiplexed.

77−In the CLI Urbit apps can process your input before you hit return. To

77+In the CLI, Urbit apps can process your input before you hit return. To

78see this in action try entering `)` as the first character at the Dojo

79prompt. Since there is no Dojo command or Hoon expression that starts

80with ')', the Dojo rejects it.

@@ -136,7 +136,7 @@ you, in turn, can sign the keys for moons. The basic idea is: your planet runs

136permanently in a data center somewhere and moons run on all your devices. Each

137planet can issue ~4 billion (`2^32`) moons.

138

139−To generate a random moon from your planet run:

139+To generate a random moon from your planet, run:

140

141```

142~your-urbit:dojo> +moon

@@ -156,14 +156,14 @@ the resulting directory is a rather unwieldy moon name.

156Here's how an example moon might be booted:

157

158```

159−$ urbit -w faswep-navred-sampel-palnet -t habref-mebsem-harrut-batlus -c mymoon

159+$ urbit -w faswep-navred-sampel-palnet -t habref-mebsem-parsym-batlus -c mymoon

160```

161

162

163Moons are automatically synced to their parent `%kids` desk, and can control

164applications on their parent planet using `|link`. You can read more about

165−those things in the [filesystem](/../filesystem) and [console](/../shell)

165+those operations in the [filesystem](/../filesystem) and [console](/../shell)

166−walkthroughs.

166+walkthroughs, respectively.

167

168

169## Continuity breaches

@@ -193,6 +193,7 @@ $ openssl req -x509 -sha256 -newkey rsa:4096 -keyout private.pem -out certificat

193$ mkdir -p your-urbit/.urb/tls

194$ mv private.pem certificate.pem your-urbit/.urb/tls

195```

196+

196These certificates would have to be manually trusted by your browser, and it's

197These certificates would have to be manually trusted by your browser, and it's

197advisable that they are used only for your localhost.

198advisable that they are used only for your localhost.

198For public-facing webservers, it would be better to create certificates for your

199For public-facing webservers, it would be better to create certificates for your

docs/using/filesystem.umd+175−43

@@ -21,7 +21,11 @@ pier directory.

22## Quickstart

24+This quick-start guide will walk you through some common commands. Follow along

25+using your Dojo. When you get a `>=` message after entering a command, the means

26+that the command was successful.

27+

24−When developing it's a good idea to use a separate desk. Create a `%sandbox`

28+When developing it's a good idea to use a separate desk. Create a `%sandbox`

25desk based on the `%home` desk:

29desk based on the `%home` desk:

27```

31```

@@ -29,8 +33,8 @@ desk based on the `%home` desk:

29```

33```

31Running `our` produces your ship-name, meaning that you can run the following

35Running `our` produces your ship-name, meaning that you can run the following

32−command instead of typing out your entire. Useful for comets, due to their very

36+command instead of typing out the entire thing. Useful for comets, due to their

33−long names!

37+very long names.

35```

39```

36|merge %sandbox our %home

40|merge %sandbox our %home

@@ -69,17 +73,17 @@ Let's see the contents of `/=sandbox=/web/md`:

69~your-urbit:dojo> +cat /=sandbox=/web/md

73~your-urbit:dojo> +cat /=sandbox=/web/md

70```

74```

72−Now let's navigate to that folder using `=dir`, which is a like `cd` in unix.

76+Now let's navigate to that folder using `=dir`, which is a like `cd` in Unix.

74```

78```

75~your-urbit:dojo> =dir /=sandbox=/web/md

79~your-urbit:dojo> =dir /=sandbox=/web/md

76```

80```

78Youl'll notice that your prompt is now `~your-urbit:dojo/sandbox/web/md>`. To

82Youl'll notice that your prompt is now `~your-urbit:dojo/sandbox/web/md>`. To

79−change back to our home directory:

83+change back to our home directory, we use `=dir` without any path.

81```

85```

82−~your-urbit:dojo> =dir

86+~your-urbit:dojo/sandbox/web/md> =dir

83```

87```

85Sync from your friend `~some-ship`'s `%experiment` desk to your

89Sync from your friend `~some-ship`'s `%experiment` desk to your

@@ -89,35 +93,138 @@ Sync from your friend `~some-ship`'s `%experiment` desk to your

89|sync %sandbox ~some-ship %experiment

93|sync %sandbox ~some-ship %experiment

90```

94```

96+If and when your sync is successful, you will receive a message:

97+

98+```

99+activated sync from %experiment on ~some-ship to %sandbox

100+```

101+

102+The ship that you sync from will get their own message indicating that you're

103+both connected as peers:

104+

105+```

106+; ~your-urbit is your neighbor.

107+```

108+

109+---

110+

92## Manual

111## Manual

112

94### Paths

113### Paths

114

96A path in Clay is a list of URL-safe text, restricted to the characters

115A path in Clay is a list of URL-safe text, restricted to the characters

97−`[a z]`,`[0 9]`, `.`, `-`, `_`, and `~`. Formally this is a `(list knot)`

116+`[a z]`,`[0 9]`, `.`, `-`, `_`, and `~`. Formally this is a `(list knot)`,

98−where each segment is a `@ta`.

117+meaning that each segment, delineated by `/`, is of the `knot` ASCII-text type.

99−

118+In other words, paths are expressed as `/foo/bar/baz`. File extensions are

100−Paths can be expressed as either `/foo/bar/baz` or `[%foo %bar %baz]`.

119+separated from file names with `/`, not `.`. Extensions are syntactically

101−The first three segments of an urbit path are `/plot/desk/case`, for

120+identical to subdirectories, except that they must terminate the path.

121+

122+Paths begin with a piece of data called a `beak`. A beak is formally a

123+`(p=ship q=desk r=case)`; it has three components, and might look like

102−example `/~dozbud/home/1`.

124+`/~dozbud-namsep/home/11`.

125+

126+The first `beak` component is `ship`, which is, as you might guess, the name of

127+an Urbit ship. The second component is `desk`, which is a workspace meant to

128+contain other directories; the default desk is `%home`. The third component is

129+`case`, which represents version information in various ways: date and time;

130+a version sequence, which is a value incremented by one whenever a file on the

131+given `desk` is modified; or an arbitrary plaintext label.

132+

133+You can find what your `beak` is at any given moment by

134+typing `%` in the Dojo and looking at the first three results.

135+

136+We use `beak`s because, unlike the current internet, the Urbit network uses a

137+global namespace. That means that a file named `example.hoon` in the `/gen`

138+directory on the `%home` desk of your ship `~lodleb-ritrul` would have a

139+universal address to anyone else on the network:

140+`~lodleb-ritrul/home/186/gen/example.hoon`. That, of

141+course, doesn't mean that everyone on the network has privileges to access that

142+path.

143+

144+The structure that combines a `beak` with further path information is called a

145+`beam`.

103

146

104##### Relative paths

147##### Relative paths

105

148

106−Relative paths are expressed using `%`, which is roughly equivalent to

149+The `%` command, which we gestured at in the above section, represents the

107−Unix `.`. `%%` is `..` and `%%%` is what you would expect `...` to be.

150+*relative path*, which is the path where you are currently working. If your

151+working directory is just your home desk, indicated by the

152+prompt `~your-planet:dojo>`, then running the command below will print your

153+working directory's `beam` information: your `beak`, and a `~` that represents

154+the empty list since no path is present.

155+

156+```

157+~your-urbit:dojo> %

158+```

159+

160+`%`s can be stacked to indicate one level further up in the hierarchy for each

161+additional `%`. Try the following command:

162+

163+```

164+~your-planet:dojo> %%%

165+```

166+

167+You'll probably notice that it only has your ship name and the empty list. The

168+two additional `%`s abandoned the `case` and the `desk` information by moving

169+up twice the hierarchy.

170+

108−There are no local relative paths. `foo/bar` must be written

171+There are no local relative paths. `/foo/bar` must be written as

109`%/foo/bar`.

172`%/foo/bar`.

110

173

111##### Substitution

174##### Substitution

112

175

113−If the default path is `/foo/bar/baz`, `/=/moo` means `/foo/moo`, and

176+You don't need to write out the explicit path every time you want to reference

114−`/=/moo/=/goo` means `/foo/moo/baz/goo`. Also, instead of `/=/=/zoo` or

177+somewhere outside of your working directory. You can substitute `=` for the

115−`/=/=/=/voo`, write `/==zoo` or `/===voo`.

178+segments of a path.

179+

180+Recall that a full address in the the Urbit namespace is a `beam`: the

181+`/ship/desk/case/path`. If you've switched to another desk before, you're

182+already familiar with substitution syntax:

183+

184+```

185+~your-urbit:dojo> =dir /=sandbox=

186+```

187+

188+The above command substitutes uses substitution to use your current `ship` and

189+`case`; only the `desk` argument, which is located between the other two, is

190+given something new. Without substitution, you would need to write:

191+

192+```

193+~your-urbit:dojo> =dir /~your-urbit/home/85

194+```

195+

196+Substitutions work the same way in `beak`s (the `ship/desk/case` part) and

197+paths. For example, if you are in the `/gen` directory, you can reference a file

198+in the `/app` directory like below. (`+cat` displays the contents of a file).

199+

200+```

201+~your-urbit:dojo/home/gen> +cat /===/app/curl/hoon

202+```

203+

204+Note what was substituted out, and note that we don't need to separate `=` with

205+`/`.

206+

207+If we changed our working directory to something called `/gen/gmail`, we could

208+access a file called

209+

210+```

211+~fasdul-balsev-lodleb-ritrul:dojo/home/gen/gmail> +cat /===/app/=/split/hoon

212+```

213+

214+Because both paths share a directory named `/gmail` at the same position in the

215+address hierarchy -- which, if you recall, is just a `list` -- the above command

216+works!

217+

218+We can do the same thing between desks. If `%sandbox` has been merged with

219+`%home`, the following command will produce the same results as the above

220+command.

221+

222+```

223+~your-urbit:dojo/home/gen/gmail> +cat /=sandbox=/app/=/split/hoon

224+```

116

225

117Most commonly this is used to avoid having to know the current revision

226Most commonly this is used to avoid having to know the current revision

118−number in the `dojo`. Instead of writing

227+number in the `dojo`: `~lodleb-ritrul/home/~2018.10.2..00.35.44..d7e8/gen/example.hoon`

119−`/~your-urbit/home/4/path/to/file` you can just write

120−`/=home=/path/to/file`.

121

228

122##### Changing directories

229##### Changing directories

123

230

@@ -135,19 +242,29 @@ This command will turn your prompt into something like this:

135~your-urbit:dojo/gen/ask>

242~your-urbit:dojo/gen/ask>

136```

243```

137

244

138−Using `=dir` without anything else uses the null path, which

245+Using `=dir` without anything else uses the null path, which returns you to

139−returns you to your home desk.

246+your home desk.

140

247

141```

248```

142~your-urbit:dojo> =dir

249~your-urbit:dojo> =dir

143```

250```

144

251

252+To go up levels in the path hierarchy, recall the relative path expression

253+`%`. Stacking them represents another level higher in the hierarchy than

254+the current working directory for each `%` beyond the initial. The command below

255+brings you one level up:

256+

257+```

258+~your-urbit:dojo/gen> =dir %%

259+```

145

260

146### Revision-control

261### Revision-control

147

262

263+##### Mount

264+

148−Syntax: `|mount /clay/path [unix-name]`

265+Syntax: `|mount /clay/path [Unix-name]`

149

266

150−Mount the `clay-path` at the unix mount point `unix-name`.

267+Mount the `clay-path` at the Unix mount point `Unix-name`.

151

268

152*Examples:*

269*Examples:*

153

270

@@ -163,8 +280,10 @@ Mounts `%/web` to `/web` inside your pier directory.

163

280

164Mounts `%/gen` to `/generators` inside your pier directory.

281Mounts `%/gen` to `/generators` inside your pier directory.

165

282

283+##### Unmount

284+

166```

285```

167−|unmount [clay-path || unix-name]

286+|unmount [clay-path || Unix-name]

168```

287```

169

288

170Unmount the path or name from Unix.

289Unmount the path or name from Unix.

@@ -263,7 +382,7 @@ version, allowing merges to be rerun.

263the reverse of `%this`. This is different from `%init` because the new

382the reverse of `%this`. This is different from `%init` because the new

264commit has both sides in its ancestry.

383commit has both sides in its ancestry.

265

384

266−`%fine` - "fast-forward" merge. This succeeds iff one head is in the

385+`%fine` - "fast-forward" merge. This succeeds if and only if one head is in the

267ancestry of the other.

386ancestry of the other.

268

387

269`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to

388`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to

@@ -299,31 +418,44 @@ annotate any conflicts, if we know how.

299

418

300### Manipulation

419### Manipulation

301

420

302−#### `|rm path`

421+##### +cat

303

422

304−Remove the data at `path`. `path` must be a path to actual node, not a

423+Syntax: `+cat path [path ...]`

305−'directory'

306

424

307−#### `|cp to from`

425+Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints their

426+contents. If that `path` is a file, the contents of the file is printed. If the

427+`path` terminates in a directory, the list of names at that path is produced.

308

428

309−Copy the file at `from` into the path `to`.

429+##### +ls

310

430

311−#### `|mv to from`

431+Syntax: `+ls path`

312

432

313−Move the file at `from` into the path `to`.

433+Similar to Unix `ls`. `+ls` takes a single `path`.

314

434

315−In Clay, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`

435+Produces a list of names at the `path`.

316−doesn't happen unless the `|cp` succeeds.

317

436

318−### Generators

437+```

438+~your-urbit:dojo> +cat %/our/home/gen/curl/hoon

439+```

319

440

320−#### `+cat path [path ...]`

441+##### |rm

321

442

322−Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints

443+Syntax: `|rm path`

323−their contents.

324

444

325−### `+ls path`

445+Remove the data at `path`. `path` must be a path to actual node, not a

446+'directory'

326

447

327−Similar to Unix `ls`. `+ls` takes a single `path`.

448+##### |cp

328

449

329−Produces a list of names at the `path`.

450+Syntax: `|cp to from`

451+

452+Copy the file at `from` into the path `to`.

453+

454+##### |mv

455+

456+Syntax: `|mv to from`

457+

458+Move the file at `from` into the path `to`.

459+

460+In Clay, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`

461+doesn't happen unless the `|cp` succeeds.

docs/using/layout.umd+13−12

@@ -41,7 +41,7 @@ LICENSE/txt app/ gen/ lib/ mar/ ren/ sec/com/ sur/ sys/ tests/ web/

42Let's step through, directory by directory.

44−## `sys/`

44+## sys/

46This is where the Arvo kernel lives. `sys/` contains:

@@ -102,7 +102,7 @@ That's it. That's the whole system.

102

103---

104

105−## `app/`

105+## app/

106

107This is where [Gall](../../tutorials/gall) apps live. Gall apps are stateful

108servers, sort of like unix daemons. One familiar one is `app/hall.hoon` which is

@@ -111,13 +111,13 @@ layer. And there's also `app/dojo.hoon` — that's your shell.

111

112---

113

114−## `gen/`

114+## gen/

115

116`gen/` holds generators. Generators are short Dojo scripts.

117

118---

119

120−## `lib/`

120+## lib/

121

122`lib/` holds shared libraries for programs. `lib/sole` is a good

123example — that's the console library that's shared by both Dojo in the

@@ -125,14 +125,14 @@ command line, and the Dojo web client.

125

126---

127

128−## `mar/`

128+## mar/

129

130This is where marks live. Marks are data type definitions used by Ford.

131A mark is like a mime-type, but specified in executable code.

132

133---

134

135−## `ren/`

135+## ren/

136

137These are web renderers. A renderer handles web requests of a particular

138type.

@@ -143,34 +143,35 @@ and `JS` and adds some routing magic for certain paths.

143

144---

145

146−## `sec/`

146+## sec/

147

148Here are security drivers that Urbit uses to log into the APIs of various

149non-Urbit services.

150

151---

152

153−## `sur/`

153+## sur/

154

155`sur/` contains shared data structures. Files in `sur` are like header

156files in C.

157

158---

159

160−## `tests/`

160+## tests/

161

162−`tests/` contains code that tests them.

162+`tests/` is the conventional place to put tests that use the +test generator and

163+lib/test/*

163

164

164---

165---

165

166

166−## `web/`

167+## web/

167

168

168Here are files publicly accessible to the web, as made possible by

169Here are files publicly accessible to the web, as made possible by

169[Eyre](../web).

170[Eyre](../web).

170

171

171---

172---

172

173

173−## `web.md`

174+## web.md

174

175

175This is the homepage for your urbit. You'll see it at

176This is the homepage for your urbit. You'll see it at

176`http://localhost:8080/` or `https://your-urbit.urbit.org/`.

177`http://localhost:8080/` or `https://your-urbit.urbit.org/`.

docs/using/messaging.umd+7−3

@@ -140,6 +140,8 @@ Last, let's create a channel we can invite some friends to:

140

141Now you can tell your friends to `;join ~your-urbit/my-channel`.

142

143+---

144+

143;h2

145;h2

144 ;div(id "manual"): Manual

146 ;div(id "manual"): Manual

145==

147==

@@ -165,7 +167,7 @@ ones you can use from within Talk: lines, URLs, Hoon and replies.

165

167

166A line is simply a string of text. Depending on the filtering rules set

168A line is simply a string of text. Depending on the filtering rules set

167by the circle's host, these may or may not include uppercase and Unicode

169by the circle's host, these may or may not include uppercase and Unicode

168−characters.

170+characters (see [filter](#filter)).

169

171

170If the line starts with `@`, it's an action (like `/me` in IRC).

172If the line starts with `@`, it's an action (like `/me` in IRC).

171

173

@@ -260,7 +262,7 @@ or if there's additional information available — as is the case with

260replies and attachments — activating the message will show you all the

262replies and attachments — activating the message will show you all the

261details.

263details.

262

264

263−You can activate the most recent line with `;`, the second-most recent

265+You can also activate the most recent line with `;`, the second-most recent

264with `;;`, and so on.

266with `;;`, and so on.

265

267

266### Creating and managing circles

268### Creating and managing circles

@@ -322,7 +324,9 @@ For example:

322sampel-palnet:talk> ;depict %coolbox 'cool messages only. NO EXCEPTIONS.'

324sampel-palnet:talk> ;depict %coolbox 'cool messages only. NO EXCEPTIONS.'

323```

325```

324

326

327+;h6

325−###### Filter

328+ ;div(id "filter"): Filter

329+==

326

330

327Syntax: `;filter %name [capitals] [unicode]`

331Syntax: `;filter %name [capitals] [unicode]`

328

332

docs/using/shell.umd+80−70

@@ -8,16 +8,12 @@

9# Shell (Dojo)

11−;div(class "row")

12− ;div(class "col-md-8")

14The Dojo is our shell; it processes system commands and returns output. It's a

12The Dojo is our shell; it processes system commands and returns output. It's a

15good place to quickly experiment with Urbit. On the surface the Dojo is just a

13good place to quickly experiment with Urbit. On the surface the Dojo is just a

16Hoon REPL. On the inside, the Dojo is a system for operating on and transforming

14Hoon REPL. On the inside, the Dojo is a system for operating on and transforming

17data in Urbit.

15data in Urbit.

19− ==

20−==

22## Quickstart

18## Quickstart

@@ -37,26 +33,25 @@ Tall-form Hoon may require multiple lines:

38```

34```

39~your-urbit:dojo> %+ add

35~your-urbit:dojo> %+ add

40−~your-urbit:dojo< 2

36+~your-urbit:dojo< 2

41~your-urbit:dojo< 2

37~your-urbit:dojo< 2

42```

38```

44−Hoon uses something called [the subject](/../../tutorials/hoon-ch1/hoon-ch1-3).

40+Hoon uses something called [the subject](../../tutorials/hoon-ch1/hoon-ch1-3).

45−The Dojo has its own subject, and that's where Hoon's equivalent of variables

41+The Dojo has its own subject, and that's where Hoon's equivalent of variables,

46−are stored.

42+called faces, are stored.

48−Use `=var` to save variable to the Dojo subject.

44+Use `=var` to save faces to the Dojo subject.

50```

46```

51~your-urbit:dojo> =foo (add 2 2)

47~your-urbit:dojo> =foo (add 2 2)

52```

48```

54Note, however, that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a

50Note, however, that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a

55−variable in a `.hoon` file in this way.

51+face in a `.hoon` file in this way.

57##### System Commands

53##### System Commands

59−

60Use `=dir` to set the current working directory:

55Use `=dir` to set the current working directory:

62```

57```

@@ -84,76 +79,92 @@ Run system commands from `:hood`, like `reload`, using `|`:

84~your-urbit:dojo> |reload %eyre

79~your-urbit:dojo> |reload %eyre

85```

80```

87−`_See the [Clay](../fileystem) page for more information on system commands.`

88−

89### Generators

82### Generators

91Generators are short Hoon scripts, saved as `.hoon` files in the `/gen`

84Generators are short Hoon scripts, saved as `.hoon` files in the `/gen`

92directory. Many Dojo commands exist in the form of generators. The syntax for

85directory. Many Dojo commands exist in the form of generators. The syntax for

93running a generator is `+genname` for a generator saved as `genname.hoon`.

86running a generator is `+genname` for a generator saved as `genname.hoon`.

88+##### +cat

89+

95−`+cat` - Accepts a path and displays the file. Similar to Unix `cat`.

90+Accepts a path and displays the file. Similar to Unix `cat`.

97```

92```

98−~your-urbit:dojo> +cat /~talsur-todres/home/gen/curl/hoon

93+~your-urbit:dojo> +cat %/gen/curl/hoon

99```

94```

100

96+##### +code

97+

101−`+code` - Generates a code to remotely log into your ship.

98+Generates a code that is used to remotely log into your ship. No

99+arguments.

102

100

103```

101```

104~your-urbit:dojo> +code

102~your-urbit:dojo> +code

105```

103```

106

104

105+##### +curl

106+

107−`+curl` - Retrives data from a URL. Accepts a `tape`. Similar to Unix

107+Retrives data from a URL. Accepts a `tape`. Similar to Unix `curl`.

108−`curl`.

109

108

110```

109```

111~your-urbit:dojo> +curl "http://nyt.com"

110~your-urbit:dojo> +curl "http://nyt.com"

112```

111```

113

112

113+##### +hello

114+

114−`+hello` - Just prints the argument. Accepts a `@ta`.

115+Just prints the argument. Accepts a `@ta`.

115

116

116```

117```

117~your-urbit:dojo> +hello 'mars'

118~your-urbit:dojo> +hello 'mars'

118```

119```

119

120

121+##### +ls

122+

120−`+ls` - Similar to Unix `ls`. Accepts a path.

123+Similar to Unix `ls`. Accepts a path.

121

124

122```

125```

123~your-urbit:dojo> +ls %/web

126~your-urbit:dojo> +ls %/web

124~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes

127~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes

125```

128```

126

129

130+##### +moon

131+

127−`+moon` - Generates a random moon from a planet. No arguments.

132+Generates a random moon from a planet. No arguments.

128

133

129```

134```

130~your-urbit:dojo> +moon

135~your-urbit:dojo> +moon

131```

136```

132

137

133−`+solid` - Compile the current state of the kernel and output a

138+##### +solid

134−noun. Usually downloaded to a file in unix. No arguments.

135

139

140+Compile the current state of the kernel and output a

141+noun. Usually downloaded to a file in unix. No arguments.

136

142

137```

143```

138~your-urbit:dojo> .urbit/pill +solid

144~your-urbit:dojo> .urbit/pill +solid

139```

145```

140

146

147+##### +test

148+

141−`+test` - Testrunner. Can test multiple generators at once, conventionally ones

149+Testrunner. Can test multiple generators at once, conventionally ones

142−in the `/test` folder. Accepts a path.

150+in the `/test` folder. Takes a path.

143

151

144```

152```

145~your-urbit:dojo> +test /lib

153~your-urbit:dojo> +test /lib

146```

154```

147

155

156+##### +ticket

157+

148−`+ticket` - Generate a ticket for an Urbit plot. Takes an Urbit name

158+Generate a ticket for an Urbit ship. Takes an Urbit name (`@p`).

149−(`@p`).

150

159

151

160

152```

161```

153~your-urbit:dojo> +ticket ~talsur-todres-your-urbit

162~your-urbit:dojo> +ticket ~talsur-todres-your-urbit

154```

163```

155

164

165+##### +tree

166+

156−`+tree` - Generate a recursive directory listing. Takes a path.

167+Generate a recursive directory listing. Takes a path.

157

168

158```

169```

159~your-urbit:dojo> +tree %/web

170~your-urbit:dojo> +tree %/web

@@ -170,7 +181,7 @@ an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quo

170~your-urbit:dojo> |hi ~binzod "you there?"

181~your-urbit:dojo> |hi ~binzod "you there?"

171```

182```

172

183

173−`|link` / `|unlink - Link / unlink a remote app. Accepts an

184+`|link` / `|unlink` - Link / unlink a remote app. Accepts an

174Urbit name and an app name.

185Urbit name and an app name.

175

186

176```

187```

@@ -191,25 +202,27 @@ number of vane names.

191~your-urbit:dojo> |reload %clay %eyre

202~your-urbit:dojo> |reload %clay %eyre

192```

203```

193

204

194−**`|reset`** - Reloads `hoon.hoon` and all modules. No arguments.

205+*`|reset`* - Reloads `hoon.hoon` and all modules. No arguments.

195

206

196```

207```

197~your-urbit:dojo> |reset

208~your-urbit:dojo> |reset

198```

209```

199

210

200−**`|start`** - Starts an app. Accepts an app name.

211+*`|start`* - Starts an app. Accepts an app name.

201

212

202```

213```

203~your-urbit:dojo> |start %curl

214~your-urbit:dojo> |start %curl

204```

215```

205

216

217+---

218+

206## Manual

219## Manual

207

220

208;h3(class "first child")

221;h3(class "first child")

209Sources and sinks

222Sources and sinks

210==

223==

211

224

212−A dojo command is either a source or a sink. A source is just something

225+A Dojo command is either a *source* or a *sink*. A source is just something

213that can be printed to your console or the result of some computation. A

226that can be printed to your console or the result of some computation. A

214sink is an *effect*: a change to the filesystem, a network message, a

227sink is an *effect*: a change to the filesystem, a network message, a

215change to your environment, or typed message to an app.

228change to your environment, or typed message to an app.

@@ -233,11 +246,11 @@ Set any environment variable:

233Make sure to note that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a

246Make sure to note that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a

234variable in a `.hoon` file in this way.

247variable in a `.hoon` file in this way.

235

248

236−#### Special Variables

249+##### Special Variables

237

250

238−There are a few special variables that the dojo maintains.

251+There are a few special variables that the Dojo maintains.

239

252

240−#### `:` - Send to app

253+##### `:` - Send to app

241

254

242`:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`.

255`:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`.

243

256

@@ -249,18 +262,18 @@ Send a `helm-hi` message to `hood`:

249

262

250Apps usually expect marked data, so `&` is often used here.

263Apps usually expect marked data, so `&` is often used here.

251

264

252−#### `*` - Save in `%clay`

265+##### `*` - Save in `%clay`

253

266

254−Save a new `md` file in `web`:

267+Save a new `.umd` file in `web`:

255

268

256```

269```

257−~your-urbit:dojo> *%/web/foo/md '# hello'

270+~your-urbit:dojo> *%/web/foo/umd '# hello'

258```

271```

259

272

260The last component of the path is expected to be the mark (or mime

273The last component of the path is expected to be the mark (or mime

261type).

274type).

262

275

263−#### `.` - Export to Unix

276+##### `.` - Export to Unix

264

277

265Export a noun to Unix with `.`:

278Export a noun to Unix with `.`:

266

279

@@ -280,7 +293,7 @@ Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`

280

293

281### Sources

294### Sources

282

295

283−#### `&` - Mark conversion

296+##### `&` - Mark conversion

284

297

285Convert between marks using `&`:

298Convert between marks using `&`:

286

299

@@ -289,14 +302,14 @@ Convert between marks using `&`:

289'<html><head></head><body><div><h1 id="-hello">hello</h1></div></body></html>'

302'<html><head></head><body><div><h1 id="-hello">hello</h1></div></body></html>'

290```

303```

291

304

292−#### `_` - Run a function

305+##### `_` - Run a function

293

306

294Use `_` to run a gate (or function):

307Use `_` to run a gate (or function):

295

308

296Write an arbitrary function and pass data to it:

309Write an arbitrary function and pass data to it:

297

310

298```

311```

299−~your-urbit:dojo> _|=({a/@} (mul a 3)) 3

312+~your-urbit:dojo> _|=([a=@] (mul a 3)) 3

3009

3139

301```

314```

302

315

@@ -307,7 +320,7 @@ Use a function to get the status code from an http request:

307301

320301

308```

321```

309

322

310−#### `+` `-` - HTTP requests

323+##### `+` `-` - HTTP requests

311

324

312`+http[s]://example.com` - sends a GET request

325`+http[s]://example.com` - sends a GET request

313

326

@@ -319,16 +332,17 @@ JSON `"hi"` in the body.

319

332

320Note that the first of these is a source while the last two are sinks.

333Note that the first of these is a source while the last two are sinks.

321

334

322−#### `+` - Generators

335+##### `+` - Generators

323

336

324−Generators are simple hoon scripts loaded from the filesystem. They live

337+Generators are simple Hoon scripts loaded from the filesystem. They live

325in `gen/`.

338in `gen/`.

326

339

327−Create a random moon (from any planet):

340+An example of a generator that is built into your urbit is `+code`. It produces

341+the code needed to log into your ship remotely.

328

342

329```

343```

330−~your-urbit:dojo> +moon

344+~your-urbit:dojo> +code

331−"moon: ~docsun-tamtem-your-urbit; ticket: ~bartug-hodbyr-fognum-ralmud"

345+fintyr-haldet-fassev-solhex

332```

346```

333

347

334### Variables

348### Variables

@@ -336,53 +350,49 @@ Create a random moon (from any planet):

336You can use `=` to set an environment variable in Dojo, but there are

350You can use `=` to set an environment variable in Dojo, but there are

337a few reserved names that have special uses.

351a few reserved names that have special uses.

338

352

339−#### `dir`

353+##### dir

340

354

341Current working `%clay` desk and revision. Read / write.

355Current working `%clay` desk and revision. Read / write.

342

356

343−**Examples:**

357+*Examples:*

344

358

345```

359```

346~your-urbit:dojo> =dir %/web

360~your-urbit:dojo> =dir %/web

347~your-urbit:dojo> +ls %

361~your-urbit:dojo> +ls %

348−404/hoon docs/ dojo/hoon lib/ listen/hoon md static/md talk/ tree/main/

362+404/hoon docs/ dojo/hoon lib/ listen/hoon md static/umd talk/ testing/umd tree/main/ unmark/ womb/

349```

363```

350

364

351−#### `lib`

365+##### lib

352

366

353−Current set of libraries (`/lib`) in your environment. Can also be set

367+Current set of libraries (`/lib`) in your environment. Can be set

354with `/+`. Read / write.

368with `/+`. Read / write.

355

369

356−**Examples:**

370+*Examples:*

357

371

358```

372```

359−~your-urbit:dojo> =lib ~[[%react ~]]

360−~your-urbit:dojo> :: this also works:

361~your-urbit:dojo> /+ react

373~your-urbit:dojo> /+ react

362~your-urbit:dojo> :: now we can use arms from lib/react.hoon

374~your-urbit:dojo> :: now we can use arms from lib/react.hoon

363~your-urbit:dojo> (react-vale:react %div)

375~your-urbit:dojo> (react-vale:react %div)

364```

376```

365

377

366−#### `sur`

378+##### sur

367

379

368−Current set of structures (`/sur`) in your environment. Can also be set

380+Current set of structures (`/sur`) in your environment. Can be set

369with `/-`. Read / write.

381with `/-`. Read / write.

370

382

371−**Examples:**

383+*Examples:*

372

384

373```

385```

374−~your-urbit:dojo> =sur ~[[%sole ~]]

375−~your-urbit:dojo> :: this also works:

376~your-urbit:dojo> /- sole

386~your-urbit:dojo> /- sole

377~your-urbit:dojo> :: now we can use arms in sur/sole.hoon

387~your-urbit:dojo> :: now we can use arms in sur/sole.hoon

378~your-urbit:dojo> `sole-effect:sole`[%bel ~]

388~your-urbit:dojo> `sole-effect:sole`[%bel ~]

379```

389```

380

390

381−#### `now`

391+##### now

382

392

383The current (128-bit `@da`) time. Read-only.

393The current (128-bit `@da`) time. Read-only.

384

394

385−**Example:**

395+*Example:*

386

396

387```

397```

388~your-urbit:dojo> now

398~your-urbit:dojo> now

@@ -390,11 +400,11 @@ The current (128-bit `@da`) time. Read-only.

390~2016.3.21..21.10.57..429a

400~2016.3.21..21.10.57..429a

391```

401```

392

402

393−#### `our`

403+##### our

394

404

395−The current urbit plot. Read-only.

405+The current urbit ship. Read-only.

396

406

397−**Example:**

407+*Example:*

398

408

399```

409```

400~your-urbit:dojo> our

410~your-urbit:dojo> our

@@ -402,11 +412,11 @@ The current urbit plot. Read-only.

402~your-urbit

412~your-urbit

403```

413```

404

414

405−#### `eny`

415+##### eny

406

416

407512 bits of entropy. Read-only.

417512 bits of entropy. Read-only.

408

418

409−**Example:**

419+*Example:*

410

420

411```

421```

412~your-urbit:dojo> eny

422~your-urbit:dojo> eny

@@ -419,5 +429,5 @@ The current urbit plot. Read-only.

419## Troubleshooting

429## Troubleshooting

420

430

421If you encounter `%dy-edit-busy` while entering commands, it is

431If you encounter `%dy-edit-busy` while entering commands, it is

422−because your dojo is blocked on a timer or an http request. Type backspace

432+because your Dojo is blocked on a timer or an HTTP request. Type backspace

423−and your dojo will end the blocked command.

433+and your Dojo will end the blocked command.

docs/using/web.umd+4

@@ -170,8 +170,12 @@ Let's quickly step through the default contents of `web/`:

170- `static.umd` - Sample static file

171- `talk/` - Talk compiled JS / CSS

172- `talk.hoon` - Page body that loads the `talk` React module.

173+- `testing.umd` - Guide to writing unit tests in Urbit

173- `tree/` - Tree compiled JS / CSS

174- `tree/` - Tree compiled JS / CSS

174- `tree.hoon` - Page body that loads the `tree` React module.

175- `tree.hoon` - Page body that loads the `tree` React module.

176+- `unmark/` - Used for testing `.umd`.

177+- `womb/` - Womb compiled by JS/CSS

178+- `womb.hoon` - Used for issuing planets on the test network.

175

179

176## Tree

180## Tree

177

181