95d9290 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

gall-guide: minor tweaks and typo fixes to lesson 3

95d9290Tinnus Napbus5 years ago

content/docs/userspace/gall-guide/3-imports-and-aliases.md+23−24

compare with master

unifiedsplit

@@ -21,20 +21,20 @@ Let's look at each in more detail:

22### `default-agent`

24−The `%default-agent` library contains a basic agent with sane default behaviours

24+The `default-agent` library contains a basic agent with sane default behaviours

25for each arm. In some cases it just crashes and prints an error message to the

26terminal, and in others it succeeds but does nothing. It has two primary uses:

28- For any agent arms you don't need, you can just have them call the matching

29− function in `%default-agent`, rather than having to manually handle events on

29+ function in `default-agent`, rather than having to manually handle events on

30 those arms.

31- A common pattern in an agent is to switch on the input of an arm with

32 [wutlus](/docs/hoon/reference/rune/wut#-wutlus) (`?+`) runes or maybe

33 [wutcol](/docs/hoon/reference/rune/wut#wutcol) (`?:`) runes. For any

34− unexpected input, you can just pass it to the relevant arm of `%default-agent`

34+ unexpected input, you can just pass it to the relevant arm of `default-agent`

35 rather than handling it manually.

37−The `%default-agent` library lives in `/lib/default-agent/hoon` of the `%base`

37+The `default-agent` library lives in `/lib/default-agent/hoon` of the `%base`

38desk, and you would typically include a copy in any new desk you created. It's

39imported at the beginning of an agent with the

40[faslus](/docs/arvo/ford/ford#ford-runes) (`/+`) rune.

@@ -50,7 +50,7 @@ typical agent core. Usually you would define an alias for it in a virtual arm

51### `dbug`

53−The `%dbug` library lets you inspect the state and `bowl` of your agent from the

53+The `dbug` library lets you inspect the state and `bowl` of your agent from the

54dojo. It includes an `agent:dbug` function which wraps your whole `agent:gall`

55`door`, adding its extra debugging functionality while transparently passing

56events to your agent for handling like usual.

@@ -116,9 +116,9 @@ A virtual arm in an agent might look something like this:

116

117`this`, `def` and `hc` are the aliases, and next to each one is the hoon

118expresion it's aliasing. Notice that unlike most things that take _n_ arguments,

119−a virtual arm is not terminated with a `==`. You can define as many

119+a virtual arm is not terminated with a `==`. You can define as many aliases as

120−aliases as you like. The three in this example are conventional ones you'd

120+you like. The three in this example are conventional ones you'd use in most

121−likely use in most agents you write. Their purposes are:

121+agents you write. Their purposes are:

122

123```hoon

124this .

@@ -132,9 +132,8 @@ agent core.

132def ~(. (default-agent this %.n) bowl)

133```

134

135−This sets up the `%default-agent` library we [described

135+This sets up the `default-agent` library we [described above](#default-agent),

136−above](#default-agent), so you can easily call its arms like `on-poke:def`,

136+so you can easily call its arms like `on-poke:def`, `on-agent:def`, etc.

137−`on-agent:def`, etc.

138

137

139```hoon

138```hoon

140hc ~(. +> bowl)

139hc ~(. +> bowl)

@@ -145,7 +144,7 @@ helper cores later, so don't worry about this for now.

145

144

146## Additional cores

145## Additional cores

147

146

148−While Gall expects a single 10-arm agent core, it's still possible to include

147+While Gall expects a single 10-arm agent core, it's possible to include

149additional cores by composing them into the subject of the agent core itself.

148additional cores by composing them into the subject of the agent core itself.

150The contents of these cores will then be available to arms of the agent core.

149The contents of these cores will then be available to arms of the agent core.

151

150

@@ -157,9 +156,9 @@ expression, which means you can just butt separate cores up against one another

157and they'll all still get composed.

156and they'll all still get composed.

158

157

159You can add as many extra cores as you'd like before the agent core, but

158You can add as many extra cores as you'd like before the agent core, but

160−typically you'd just add one containing structure definitions for the agent's

159+typically you'd just add one containing type definitions for the agent's state,

161−state, as well as any other useful structures. We'll look at the state in more

160+as well as any other useful structures. We'll look at the state in more detail

162−detail in the next lesson.

161+in the next lesson.

163

162

164## Example

163## Example

165

164

@@ -197,9 +196,9 @@ into the subject of our agent so they're available for use. You can read more

197about Ford runes in the [Ford section of the vane

196about Ford runes in the [Ford section of the vane

198documenation](/docs/arvo/ford/ford#ford-runes).

197documenation](/docs/arvo/ford/ford#ford-runes).

199

198

200−Next, we've added an extra core. Notive how it's not explicitly composed, since

199+Next, we've added an extra core. Notice how it's not explicitly composed, since

201−the build system will do that for use. In this case we've just added a single

200+the build system will do that for us. In this case we've just added a single

202−`card` arm, which just makes it simpler to reference the `card:agent:gall` type.

201+`card` arm, which makes it simpler to reference the `card:agent:gall` type.

203

202

204After that core, we call `agent:dbug` with our whole agent core as its argument.

203After that core, we call `agent:dbug` with our whole agent core as its argument.

205This allows us to use the `dbug` features described earlier.

204This allows us to use the `dbug` features described earlier.

@@ -213,7 +212,7 @@ of aliases:

213```

212```

214

213

215In most of the arms, you see we've been able to replace the dummy code with

214In most of the arms, you see we've been able to replace the dummy code with

216−simple calls to the corresponding arms of `%default-agent`, which we set up and

215+simple calls to the corresponding arms of `default-agent`, which we set up and

217aliased as `def` in the virtual arm. We've also replaced the old `..on-init`

216aliased as `def` in the virtual arm. We've also replaced the old `..on-init`

218with our alias `this` in the `on-init` arm as an example - it makes things a bit

217with our alias `this` in the `on-init` arm as an example - it makes things a bit

219simpler.

218simpler.

@@ -264,14 +263,14 @@ idea of its basic usage.

264The key takeaways are:

263The key takeaways are:

265

264

266- Libraries can be imported with `/+`.

265- Libraries can be imported with `/+`.

267−- `%default-agent` is a library that provides default behaviours for Gall agent

266+- `default-agent` is a library that provides default behaviours for Gall agent

268 arms.

267 arms.

269−- `%dbug` is a library that lets you inspect the state and `bowl` of an agent

268+- `dbug` is a library that lets you inspect the state and `bowl` of an agent

270 from the dojo, with the `+dbug` generator.

269 from the dojo, with the `+dbug` generator.

271- Convenient aliases for hoon expressions can be defined in a virtual arm with

270- Convenient aliases for hoon expressions can be defined in a virtual arm with

272 the [lustar](/docs/hoon/reference/rune/lus#-lustar) (`+*`) rune.

271 the [lustar](/docs/hoon/reference/rune/lus#-lustar) (`+*`) rune.

273- `this` is a conventional alias for the agent core itself.

272- `this` is a conventional alias for the agent core itself.

274−- `def` is a conventional alias for accessing arms in the `%default-agent`

273+- `def` is a conventional alias for accessing arms in the `default-agent`

275 library.

274 library.

276- Extra cores can be composed into the subject of the agent core. The

275- Extra cores can be composed into the subject of the agent core. The

277 composition is done implicitly by the build system. Typically we'd include one

276 composition is done implicitly by the build system. Typically we'd include one

@@ -280,14 +279,14 @@ The key takeaways are:

280

279

281## Exercises

280## Exercises

282

281

283−- Run through the [Example](#example) yourself on a fake ship if you've not done

282+- Run through the [example](#example) yourself on a fake ship if you've not done

284 so already.

283 so already.

285- Have a read through the [Ford rune

284- Have a read through the [Ford rune

286 documentation](/docs/arvo/ford/ford#ford-runes) for details about importing

285 documentation](/docs/arvo/ford/ford#ford-runes) for details about importing

287 libraries, structures and other things.

286 libraries, structures and other things.

288- Try the `+dbug` generator out on some other agents, like `:settings-store +dbug`, `:btc-wallet +dbug`, etc, and try some of its options [described

287- Try the `+dbug` generator out on some other agents, like `:settings-store +dbug`, `:btc-wallet +dbug`, etc, and try some of its options [described

289 above](#dbug).

288 above](#dbug).

290−- Have a quick look over the source of the `%default-agent` library, locate at

289+- Have a quick look over the source of the `default-agent` library, located at

291 `/lib/default-agent.hoon` in the `%base` desk. We've not yet covered what the

290 `/lib/default-agent.hoon` in the `%base` desk. We've not yet covered what the

292 different arms do but it's still useful to get a general idea, and you'll

291 different arms do but it's still useful to get a general idea, and you'll

293 likely want to refer back to it later.

292 likely want to refer back to it later.