using/shell.udon · urbit.org

git.iko.soy/urbit.org

on 999b2ef help sign in

urbit.org/using/shell.udon

432 lines 8.4 kB history raw

1:- :~ navhome/'/docs/'

2 navuptwo/'true'

3 next/'true'

4 sort/'3'

5 title/'Shell (Dojo)'

6 ==

7;>

9# Shell (Dojo)

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

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

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

14data in Urbit.

17## Quickstart

19You can use the Dojo to run arbitrary Hoon code, as well as non-Hoon system

20commands.

22##### Math

24Evaluate a Hoon expression (whitespace matters):

26```

27~your-urbit:dojo> (add 2 2)

28~your-urbit:dojo> %+ add 2 2

29```

31Tall-form Hoon may require multiple lines:

33```

34~your-urbit:dojo> %+ add

35~your-urbit:dojo< 2

36~your-urbit:dojo< 2

37```

39Hoon uses something called [the subject](/docs/learn/hoon/hoon-tutorial/the-subject-and-its-legs).

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

41called faces, are stored.

43Use `=var` to save faces to the Dojo subject.

45```

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

47```

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

50face in a `.hoon` file in this way.

52##### System Commands

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

56```

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

58```

60(`%` represents your current directory. For a complete explanation on urbit

61paths, see the [filesystem section](../filesystem))

63Generators (files in `/gen`) are run with `+`:

65```

66~your-urbit:dojo> +hello 'world'

67```

69Save output to a file in `%clay` with `*`:

71```

72~your-urbit:dojo> *some/file/path/hoon 'hello world'

73```

75Run system commands from `:hood`, like `reload`, using `|`:

77```

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

79```

81### Generators

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

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

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

87##### +cat

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

91```

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

93```

95##### +code

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

98arguments.

100```

101~your-urbit:dojo> +code

102```

103

104##### +curl

105

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

107

108```

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

110```

111

112##### +hello

113

114Just prints the argument. Accepts a `@ta`.

115

116```

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

118```

119

120##### +ls

121

122Similar to Unix `ls`. Accepts a path.

123

124```

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

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

127```

128

129##### +moon

130

131Generates a random moon from a planet. No arguments.

132

133```

134~your-urbit:dojo> +moon

135```

136

137##### +solid

138

139Compile the current state of the kernel and output a

140noun. Usually downloaded to a file in unix. No arguments.

141

142```

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

144```

145

146##### +test

147

148Testrunner. Can test multiple generators at once, conventionally ones

149in the `/test` folder. Takes a path.

150

151```

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

153```

154

155##### +ticket

156

157Generate a ticket for an urbit ship. Takes an urbit name (`@p`).

158

159

160```

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

162```

163

164##### +tree

165

166Generate a recursive directory listing. Takes a path.

167

168```

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

170```

171

172### Hood

173

174The hood is the system daemon. See `gen/hood` and `app/hood`.

175

176`|hi` - Sends a direct message. Sort of like Unix `write`. Accepts

177an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quotes).

178

179```

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

181```

182

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

184Urbit name and an app name.

185

186```

187~your-urbit:dojo> |link ~talsur-todres %octo

188```

189

190`|mass` - Prints the current memory usage of all the kernel modules.

191No arguments.

192

193```

194~your-urbit:dojo> |mass

195```

196

197`|reload` - Reloads a kernel module (vane) from source. Accepts any

198number of vane names.

199

200```

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

202```

203

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

205

206```

207~your-urbit:dojo> |reset

208```

209

210*`|start`* - Starts an app. Accepts an app name.

211

212```

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

214```

215

216---

217

218## Manual

219

220;h3(class "first child")

221Sources and sinks

222==

223

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

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

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

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

228

229Sources can be chained together, but we can only produce one effect per

230command.

231

232### Sinks

233

234##### `=` - Set variable

235

236Set any environment variable:

237

238```

239~your-urbit:dojo> =foo 42

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

241

24244

243```

244

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

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

247

248##### Special Variables

249

250There are a few special variables that the Dojo maintains.

251

252##### `:` - Send to app

253

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

255

256Send a `helm-hi` message to `hood`:

257

258```

259~your-urbit:dojo> :hood &helm-hi 'hi'

260```

261

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

263

264##### `*` - Save in `%clay`

265

266Save a new `.udon` ([Udon](../udon)) file in `web`:

267

268```

269~your-urbit:dojo> *%/web/foo/udon '# hello'

270```

271

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

273type).

274

275##### `.` - Export to Unix

276

277Export a noun to Unix with `.`:

278

279```

280~your-urbit:dojo> .foo/bar/baz (add 2 2)

281```

282

283Which creates a file at `pier/.urb/put/foo/bar.baz`.

284

285This is very often used with `+solid`:

286

287```

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

289```

290

291Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`

292

293### Sources

294

295##### `&` - Mark conversion

296

297Convert between marks using `&`:

298

299```

300~your-urbit:dojo> &html &md '# hello'

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

302```

303

304##### `_` - Run a function

305

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

307

308Write an arbitrary function and pass data to it:

309

310```

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

3129

313```

314

315Use a function to get the status code from an http request:

316

317```

318~your-urbit:dojo> _|=([p=@ud q=* r=*] p) +http://google.com

319301

320```

321

322##### `+` `-` - HTTP requests

323

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

325

326`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the

327JSON `"hi"` in the body.

328

329`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the

330JSON `"hi"` in the body.

331

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

333

334##### `+` - Generators

335

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

337in `gen/`.

338

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

340the code needed to log into your ship remotely.

341

342```

343~your-urbit:dojo> +code

344fintyr-haldet-fassev-solhex

345```

346

347### Variables

348

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

350a few reserved names that have special uses.

351

352##### dir

353

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

355

356*Examples:*

357

358```

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

360~your-urbit:dojo> +ls %

361404/hoon docs/ dojo/hoon lib/ listen/hoon md static/udon talk/ testing/udon tree/main/ unmark/ womb/

362```

363

364##### lib

365

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

367with `/+`. Read / write.

368

369*Examples:*

370

371```

372~your-urbit:dojo> /+ react

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

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

375```

376

377##### sur

378

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

380with `/-`. Read / write.

381

382*Examples:*

383

384```

385~your-urbit:dojo> /- sole

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

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

388```

389

390##### now

391

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

393

394*Example:*

395

396```

397~your-urbit:dojo> now

398:: produces

399~2016.3.21..21.10.57..429a

400```

401

402##### our

403

404The current urbit ship. Read-only.

405

406*Example:*

407

408```

409~your-urbit:dojo> our

410:: produces

411~your-urbit

412```

413

414##### eny

415

416512 bits of entropy. Read-only.

417

418*Example:*

419

420```

421~your-urbit:dojo> eny

422:: produces

423\/0vnt.d474o.gpahj.jcf3o.448fh.2lamb.82ljm.8ol8u.b02vi.mrvvp.b7et2.knb7m.l8he\/

424 8.8qb9s.drm36.77n9b.a0qst.30g03.l5lb5.nvsbc.v39tn

425\/

426```

427

428## Troubleshooting

429

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

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

432and your Dojo will end the blocked command.