c637868 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

Merge branch 'master' into master

c637868rmariani8 years ago

docs/about/glossary.md+48−50

compare with master

unifiedsplit

@@ -1,7 +1,6 @@

1---

2navhome: /docs/

3navuptwo: true

4−next: true

5sort: 5

4sort: 5

6title: Glossary

5title: Glossary

7---

6---

@@ -30,14 +29,14 @@ classed by the number of bits in their address:

31Any ship can be called an "urbit."

30Any ship can be called an "urbit."

33−> You can find a longer-form summary here:

32+> You can find a longer-form summary here:

34> [`urbit.org/posts/address-space/`](https://urbit.org/posts/address-space/).

33> [`urbit.org/posts/address-space/`](https://urbit.org/posts/address-space/).

35−

34+

36An Urbit identity is a string like `~firbyr-napbes`. It means nothing,

35An Urbit identity is a string like `~firbyr-napbes`. It means nothing,

37but it's easy to remember and say out loud. `~firbyr-napbes` is actually

36but it's easy to remember and say out loud. `~firbyr-napbes` is actually

38−just a 32-bit number (`3.237.967.392`, to be exact), like an IP address,

37+just a 32-bit number (`3.237.967.392`, to be exact), like an IP address,

39−that we turn into a human-memorable string. The full name of this string

38+that we turn into a human-memorable string. The full name of this string

40−can be viewed by typing `our` in the Dojo, Urbit's shell. This is useful

39+can be viewed by typing `our` in the Dojo, Urbit's shell. This is useful

41when running a ship with a longer name, such as a *moon* or a *comet*.

40when running a ship with a longer name, such as a *moon* or a *comet*.

43Technically, an urbit is a secure digital identity that you own and

42Technically, an urbit is a secure digital identity that you own and

@@ -124,7 +123,7 @@ An atom type is *warm* or *cold* based on whether the constant exists.

124#### aura

123#### aura

125

124

126An *aura* is a soft atom type. It represents the structure of an

125An *aura* is a soft atom type. It represents the structure of an

127−atom in a string beginning with `@`. An aura may represent print

126+atom in a string beginning with `@`. An aura may represent print

128format or other semantics. Its constraints on the value of an

127format or other semantics. Its constraints on the value of an

129atom aren't enforced in any way.

128atom aren't enforced in any way.

130

129

@@ -148,8 +147,8 @@ You can find the list of all auras [here](../../hoon/atom/sand/).

148

147

149#### core

148#### core

150

149

151−A _core_ is a [cell](#-nock-cell) of `[code data]`, where we call the

150+A _core_ is a [cell](#-nock-cell) of `[code data]`, where we call the

152−code head the _battery_ and the data tail the _payload_. All code-data

151+code head the _battery_ and the data tail the _payload_. All code-data

153structures in normal languages (functions, objects, modules, etc.)

152structures in normal languages (functions, objects, modules, etc.)

154become _core_s in Hoon.

153become _core_s in Hoon.

155

154

@@ -158,24 +157,24 @@ become _core_s in Hoon.

158

157

159*See [basic types](../../hoon/basic)*.

158*See [basic types](../../hoon/basic)*.

160

159

161−#### face

160+#### face

162

161

163−A Hoon _face_ is a labeled subtree.

162+A Hoon _face_ is a labeled subtree.

164

163

165Hoon has no scope or symbol-table; there is only the subject. To

164Hoon has no scope or symbol-table; there is only the subject. To

166"declare" a "variable" is to construct a new subject:

165"declare" a "variable" is to construct a new subject:

167`[name=value old-subject]`.

166`[name=value old-subject]`.

168

167

169−A face is a type that wraps a named symbol (of [aura](#-aura)

168+A face is a type that wraps a named symbol (of [aura](#-aura)

170`@tas`) around another type.

169`@tas`) around another type.

171

170

172*See [advanced types](../../hoon/advanced/#-face-aliases-and-bridges)*.

171*See [advanced types](../../hoon/advanced/#-face-aliases-and-bridges)*.

173

172

174#### gate

173#### gate

175

174

176−A _gate_ is a [core](#-core) with one [arm](#-arm) -- Hoon's closest

175+A _gate_ is a [core](#-core) with one [arm](#-arm) -- Hoon's closest

177analog to a function/lambda/closure. To call a gate on an argument,

176analog to a function/lambda/closure. To call a gate on an argument,

178−replace the sample (at [tree address](../../hoon/limb/limb/) `+6`

177+replace the sample (at [tree address](../../hoon/limb/limb/) `+6`

179in the core) with the argument, and then compute the arm.

178in the core) with the argument, and then compute the arm.

180

179

181The payload of a gate has a shape of `[sample context]`.

180The payload of a gate has a shape of `[sample context]`.

@@ -184,33 +183,33 @@ The payload of a gate has a shape of `[sample context]`.

184- <h6 id="-gate-context">context:</h6> the subject in which the gate was defined

183- <h6 id="-gate-context">context:</h6> the subject in which the gate was defined

185

184

186*See [basic types](../../hoon/basic/#-core-p-type-q-map-term-type),

185*See [basic types](../../hoon/basic/#-core-p-type-q-map-term-type),

187−[`%-` ("cenhep")](../../hoon/rune/cen/hep/) (the

186+[`%-` ("cenhep")](../../hoon/rune/cen/hep/) (the

188[rune](#-rune) for calling a `gate`).*

187[rune](#-rune) for calling a `gate`).*

189

188

190#### <h4 id="-a-hoon">hoon</h4>

189#### <h4 id="-a-hoon">hoon</h4>

191

190

192−A [`hoon`](../../hoon/reference/) is the result of parsing a Hoon source

191+A [`hoon`](../../hoon/reference/) is the result of parsing a Hoon source

193−expression into an AST node. These AST nodes are nouns, like all

192+expression into an AST node. These AST nodes are nouns, like all

194−other Hoon data. Because every Hoon program is, in its entirety, a

193+other Hoon data. Because every Hoon program is, in its entirety, a

195−single expression of Hoon, the result of parsing the whole thing

194+single expression of Hoon, the result of parsing the whole thing

196into an AST is a single `hoon`.

195into an AST is a single `hoon`.

197

196

198−A hoon is a tagged union of the form `[%tag data]`, where the tag

197+A hoon is a tagged union of the form `[%tag data]`, where the tag

199−is a constant such as `%brts` (from the source [rune](#-rune) `|=`,

198+is a constant such as `%brts` (from the source [rune](#-rune) `|=`,

200−i.e. "bartis"), and is matched up with the appropriate type of data

199+i.e. "bartis"), and is matched up with the appropriate type of data

201−(often more `hoon`s, from source subexpressions). For example, the

200+(often more `hoon`s, from source subexpressions). For example, the

202expression `:-(2 17)`, once parsed into an AST, becomes the following:

201expression `:-(2 17)`, once parsed into an AST, becomes the following:

203

202

204```

203```

205[%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]]

204[%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]]

206```

205```

207

206

208−The `%clhp` is produced from the rune `:-` (i.e. "colhep"). The 2 and

207+The `%clhp` is produced from the rune `:-` (i.e. "colhep"). The 2 and

209−17 have each been parsed as `%sand`-tagged hoons, which represent

208+17 have each been parsed as `%sand`-tagged hoons, which represent

210−atoms (in this case each with an aura of `%ud`, i.e. unsigned

209+atoms (in this case each with an aura of `%ud`, i.e. unsigned

211decimal).

210decimal).

212

211

213−To parse Hoon source into a hoon AST, use `ream` on a `cord`

212+To parse Hoon source into a hoon AST, use `ream` on a `cord`

214containing Hoon source. Try the following in [Dojo](../../using/shell):

213containing Hoon source. Try the following in [Dojo](../../using/shell):

215

214

216```

215```

@@ -225,7 +224,7 @@ The result should be:

225

224

226#### limb

225#### limb

227

226

228−A _limb_ is an attribute or variable reference.

227+A _limb_ is an attribute or variable reference.

229

228

230To resolve a *limb* named "foo", the subject is searched depth-first,

229To resolve a *limb* named "foo", the subject is searched depth-first,

231head-first for either a face named "foo" or a core with an arm of

230head-first for either a face named "foo" or a core with an arm of

@@ -247,10 +246,10 @@ A _loobean_ is a Hoon boolean. `0` (`%.y`) is *yes*, `1` (`%.n`) is *no*.

247

246

248#### mark

247#### mark

249

248

250−A _mark_ is Urbit's version of a MIME type, if a MIME type was an

249+A _mark_ is Urbit's version of a MIME type, if a MIME type was an

251−executable specification. The mark is just a label that's used as a path

250+executable specification. The mark is just a label that's used as a path

252−to a local source file in the Arvo filesystem. This source file defines

251+to a local source file in the Arvo filesystem. This source file defines

253−a core that can mold untrusted data, diff and patch, convert to other

252+a core that can mold untrusted data, diff and patch, convert to other

254marks, etc.

253marks, etc.

255

254

256If this sounds like magic, it isn't quite magic. There's no way

255If this sounds like magic, it isn't quite magic. There's no way

@@ -273,11 +272,11 @@ properties of the type of a compatible core). The default is `gold`

273

272

274#### mold

273#### mold

275

274

276−A _mold_ is an idempotent [gate](#-gate) (function), accepting any noun,

275+A _mold_ is an idempotent [gate](#-gate) (function), accepting any noun,

277and producing a range with a type, a set of nouns.

276and producing a range with a type, a set of nouns.

278

277

279−Molds act as type constructor/validators in Hoon. An example: Arvo

278+Molds act as type constructor/validators in Hoon. An example: Arvo

280−[marks](#-marks) use Hoon's type system under the hood via molds to

279+[marks](#-marks) use Hoon's type system under the hood via molds to

281validate untrusted network data.

280validate untrusted network data.

282

281

283Here's some common mold terminology:

282Here's some common mold terminology:

@@ -288,9 +287,9 @@ Here's some common mold terminology:

288

287

289*See [mold hoons](../../hoon/rune/buc/).*

288*See [mold hoons](../../hoon/rune/buc/).*

290

289

291−#### nest

290+#### nest

292

291

293−`nest` is an internal Hoon function on two types which performs a type

292+`nest` is an internal Hoon function on two types which performs a type

294compatibility test. `nest` produces yes if the

293compatibility test. `nest` produces yes if the

295set of nouns in the second type is provably a subset of the first.

294set of nouns in the second type is provably a subset of the first.

296If `nest` produces no, the Hoon programmer will receive a `nest-fail`

295If `nest` produces no, the Hoon programmer will receive a `nest-fail`

@@ -301,12 +300,12 @@ error. This is one of the most commons errors in Hoon programming.

301

300

302#### rune

301#### rune

303

302

304−A Hoon _rune_ is a pair of ASCII symbols used to begin a

303+A Hoon _rune_ is a pair of ASCII symbols used to begin a

305[Hoon expression](#-a-hoon).

304[Hoon expression](#-a-hoon).

306

305

307−For example, the rune [`?:`](../../hoon/rune/wut/col/) is

306+For example, the rune [`?:`](../../hoon/rune/wut/col/) is

308−Hoon's most common conditional, a branch on a boolean test. The first

307+Hoon's most common conditional, a branch on a boolean test. The first

309−symbol in a rune represents a family of related runes. For example, the

308+symbol in a rune represents a family of related runes. For example, the

310[`?` family](../../hoon/rune/wut/) are all conditionals.

309[`?` family](../../hoon/rune/wut/) are all conditionals.

311

310

312The result of parsing a Hoon source expression—the rune, followed

311The result of parsing a Hoon source expression—the rune, followed

@@ -336,32 +335,31 @@ Runes have two syntactic forms, _tall_ and _flat_:

336 4

335 4

337 ```

336 ```

338

337

339−Tall hoons can contain flat hoons, but not vice versa. All irregular

338+Tall hoons can contain flat hoons, but not vice versa. All irregular

340forms are flat.

339forms are flat.

341

340

342*See [hoon concept](../../hoon/concepts/#-hoon),

341*See [hoon concept](../../hoon/concepts/#-hoon),

343[expressions](../../hoon/rune/), and [syntax](../../hoon/syntax/)*.

342[expressions](../../hoon/rune/), and [syntax](../../hoon/syntax/)*.

344

343

345−#### slot

344+#### slot

346

345

347`slot` is the name for Hoon's tree addressing scheme.

346`slot` is the name for Hoon's tree addressing scheme.

348

347

349Every cell has a head and a tail, each of which may be either an atom or

348Every cell has a head and a tail, each of which may be either an atom or

350a cell. Therefore every noun is a binary tree. `+1` or `.` resolves to

349a cell. Therefore every noun is a binary tree. `+1` or `.` resolves to

351the whole cell (technically this would work against an atom as well).

350the whole cell (technically this would work against an atom as well).

352−The head of `+n` is `+2n`, the tail is `+(2n+1)`.

351+The head of `+n` is `+2n`, the tail is `+(2n+1)`.

353

352

354#### type

353#### type

355

354

356−A Hoon _type_ defines a set (finite or infinite) of nouns and ascribes

355+A Hoon _type_ defines a set (finite or infinite) of nouns and ascribes

357−some semantics to it. There is no direct syntax for defining

356+some semantics to it. There is no direct syntax for defining

358types; they are always defined by inference (i.e., by

357types; they are always defined by inference (i.e., by

359[`mint`](#-mint)), usually using a constructor ([`mold`](#-mold)).

358[`mint`](#-mint)), usually using a constructor ([`mold`](#-mold)).

360

359

361−All types are assembled out of base types defined in `++type`.

360+All types are assembled out of base types defined in `++type`.

362−(Look up `++ type` in hoon.hoon for examples.) When the compiler

361+(Look up `++ type` in hoon.hoon for examples.) When the compiler

363−does type-inference on a program, it assembles complex types out

362+does type-inference on a program, it assembles complex types out

364of the simpler built-in types.

363of the simpler built-in types.

365

364

366*See [basic types](../../hoon/basic/).*

365*See [basic types](../../hoon/basic/).*

367−

docs/arvo/basic.md+22−22

@@ -19,14 +19,14 @@ To run this code, you'll need an urbit, and will have to either sync or copy the

20## Installation

22−First, you'll need a running urbit. Follow our urbit.org [install

22+First, you'll need a running urbit. Follow our urbit.org [install

23−instructions](https://urbit.org/docs/using/install), then

23+instructions](https://urbit.org/docs/using/install), then

24[setup](https://urbit.org/docs/using/setup) and urbit.

26−Follow the *Network install* below if your urbit is running on the live network

26+Follow the *Network install* below if your urbit is running on the live network

27−(comets are usually best for development). Follow the *Local install* instead

27+(comets are usually best for development). Follow the *Local install* instead

28−if you're on a

28+if you're on a

29−[fake ship](https://urbit.org/fora/posts/~2017.1.5..21.31.04..20f3~/) or are

29+[fake ship](https://urbit.org/fora/posts/~2017.1.5..21.31.04..20f3~/) or are

30otherwise experiencing problems with the network install.

32### Network install

@@ -107,26 +107,26 @@ Here is the hoon solution (which should be in your pier directory under

107 ::

108 |%

109 ++ three

110− |= a/@

110+ |= a/@

111− =| b/@

111+ =| b/@

112 |- ^- @u

113 ?: (lth a b)

114 0

115 (add b $(b (add 3 b)))

116 ::

117 ++ five

118− |= a/@

118+ |= a/@

119− =| b/@

119+ =| b/@

120 |- ^- @

121 ?: (lte a b)

122 0

123 ?: =((mod b 3) 0)

124− $(b (add b 5))

124+ $(b (add b 5))

125 (add b $(b (add b 5)))

126 ::

127− ++ sum

127+ ++ sum

128 |= a/@u

129− (add (five a) (three a))

129+ (add (five a) (three a))

130 --

131

132> Hoon is not generally whitespace sensitive, but we do have two

@@ -190,11 +190,11 @@ Using this scheme, we would pronounce `?:` as 'wutcol'.

190### Lines 14-37

191

192Now let's quickly walk through this code line-by-line. Lines 14-37 are wrapped

193−in a `|%` ('[barcen](../../hoon/twig/bar-core/cen-core/)'), which produces a

193+in a `|%` ('[barcen](../../hoon/rune/bar/cen/)'), which produces a

194core. Cores are a fundamental datatype in Hoon, similar to a struct, class, or

195object. A core is just a map of names to any kind of code, whether it be

196−functions or data. Each element, called an arm, in this map begins with a `++`

196+functions or data. Each element, called an arm, in this map begins with a `++`

197−followed by the name and the corresponding code. Since `|%` takes an arbitrary

197+followed by the name and the corresponding code. Since `|%` takes an arbitrary

198number of children, it needs to be closed with a `--`.

199

200> `++` ('luslus') is not technically a rune, since it is only used in

@@ -209,7 +209,7 @@ Let's step into each of the three arms within our core.

209 (add (five a) (three a))

210 --

211

212−`|=` ('[bartis](../../hoon/twig/bar-core/tis-gate/)') produces a function, much like a lambda in lisp. It

212+ `|=` ('[bartis](../../hoon/rune/bar/tis/)') produces a function, much like a lambda in lisp. It

213takes two children:

214

2151. A set of argument(s). In this case our argument set only contains

@@ -234,7 +234,7 @@ takes two children:

234As above, `++three` takes an integer argument, `a`, and then executes

235the remainder of the code with `a` set to the actual arguments.

236

237−Similarly, `=|` ('[tisbar](../../hoon/twig/tis-flow/bar-new/)') pushes its first child, `b` into our context

237+Similarly, `=|` ('[tisbar](../../hoon/rune/tis-flow/bar-new/)') pushes its first child, `b` into our context

238(in other words, it declares a variable `b`) and executes the remainder

239of the code. However, `b` is not an argument; `=|` sets `b` to the

240default value of whatever type it is declared as. Since the default

@@ -252,10 +252,10 @@ value of an atom is `0`, b is set to `0`.

252So now we have two variables: `a` is set to our input, and `b` is

253initialized to `0`.

254

255−One way to think about `|-` ('[barhep](../../hoon/twig/bar-core/hep-loop/)') is that it lays down a recursion

255+One way to think about `|-` ('[barhep](../../hoon/rune/bar/hep/)') is that it lays down a recursion

256point. More on this later.

257

258−`^-` ('[kethep](../../hoon/core/ket-cast/hep-cast/)') is just a cast that sets the result of the remainder of

258+`^-` ('[kethep](../../hoon/rune/ket/hep/)') is just a cast that sets the result of the remainder of

259the code to an unsigned integer, `@u`.

260

261In pseudocode, the last three lines read like this: if `a` is less than

@@ -299,7 +299,7 @@ our cheatsheat at the bottom.

299 =(a b) test equality

300 (function args ...) call function with args

301

302−Lookup each of these expressions (and all others!) in the [Twig Expressions](../../hoon/twig/) definition.

302+Lookup each of these expressions (and all others!) in the [Rune Expressions](../../hoon/rune/) definition.

303

304### New material

305

@@ -324,7 +324,7 @@ Lookup each of these expressions (and all others!) in the [Twig Expressions](../

324 Surrounding a function with `()` is an irregular wide form syntax for

325 calling a function with *N* arguments. More on this later.

326

327−2. For a set of multiple arguments following `|=` ('[bartis](../../hoon/twig/bar-core/tis-gate/)'), use `{` 'kel' and `}` 'ker.' For example: `{a/@u b/@u}`.

327+2. For a set of multiple arguments following `|=` ('[bartis](../../hoon/rune/bar/tis/)'), use `{` 'kel' and `}` 'ker.' For example: `{a/@u b/@u}`.

328

3293. `:-` makes a cell of values. The irregular wide form of this is

330 `[a b]`, with two expressions separated by a single space. While the

docs/arvo/internals.md+30−28

@@ -1,6 +1,8 @@

1---

2navhome: /docs/

3+next: false

3sort: 22

4sort: 22

5+Title: Internals

4---

6---

6# Arvo internals

8# Arvo internals

@@ -11,13 +13,13 @@ Arvo is composed of modules called vanes:

12<hr></hr>

14<hr></hr>

14−At a high level `%arvo` takes a mess of unix io events and turns them

16+At a high level `%arvo` takes a mess of Unix I/O events and turns them

15into something clean and structured for the programmer.

17into something clean and structured for the programmer.

17`%arvo` is designed to avoid the usual state of complex event networks:

19`%arvo` is designed to avoid the usual state of complex event networks:

18event spaghetti. We keep track of every event's cause so that we have a

20event spaghetti. We keep track of every event's cause so that we have a

19clear causal chain for every computation. At the bottom of every chain

21clear causal chain for every computation. At the bottom of every chain

20−is a unix io event, such as a network request, terminal input, file

22+is a Unix I/O event, such as a network request, terminal input, file

21sync, or timer event. We push every step in the path the request takes

23sync, or timer event. We push every step in the path the request takes

22onto the chain until we get to the terminal cause of the computation.

24onto the chain until we get to the terminal cause of the computation.

23Then we use this causal stack to route results back to the caller.

25Then we use this causal stack to route results back to the caller.

@@ -29,7 +31,7 @@ The `%arvo` causal stack is called a `++duct`. This is represented

29simply as a list of paths, where each path represents a step in the

31simply as a list of paths, where each path represents a step in the

30causal chain. The first element in the path is the first letter of

32causal chain. The first element in the path is the first letter of

31whichever vane handled that step in the computation, or the empty span

33whichever vane handled that step in the computation, or the empty span

32−for unix.

34+for Unix.

34Here's a duct that was recently observed in the wild:

36Here's a duct that was recently observed in the wild:

@@ -44,20 +46,20 @@ Here's a duct that was recently observed in the wild:

44This is the duct the timer vane receives when "timer" sample app asks

46This is the duct the timer vane receives when "timer" sample app asks

45the timer vane to set a timer. This is also the duct over which the

47the timer vane to set a timer. This is also the duct over which the

46response is produced at the specified time. Unix sent a terminal

48response is produced at the specified time. Unix sent a terminal

47−keystroke event (enter), and arvo routed it to %dill(our terminal),

49+keystroke event (enter), and Arvo routed it to `%dill` (our terminal),

48−which passed it on to the %gall app terminal, which sent it to shell,

50+which passed it on to the `%gall` app terminal, which sent it to shell,

49its child, which created a new child (with process id 4), which on

51its child, which created a new child (with process id 4), which on

50startup asked the timer vane to set a timer.

52startup asked the timer vane to set a timer.

52The timer vane saves this duct, so that when the specified time arrives

54The timer vane saves this duct, so that when the specified time arrives

53−and unix sends a wakeup event to the timer vane, it can produce the

55+and Unix sends a wakeup event to the timer vane, it can produce the

54response on the same duct. This response is routed to the place we

56response on the same duct. This response is routed to the place we

55popped off the top of the duct, i.e. the time app. This app produces the

57popped off the top of the duct, i.e. the time app. This app produces the

56text "ding", which falls down to the shell, which drops it through to

58text "ding", which falls down to the shell, which drops it through to

57the terminal. Terminal drops this down to dill, which converts it into

59the terminal. Terminal drops this down to dill, which converts it into

58−an effect that unix will recognize as a request to print "ding" to the

60+an effect that Unix will recognize as a request to print "ding" to the

59screen. When dill produces this, the last path in the duct has an

61screen. When dill produces this, the last path in the duct has an

60−initial element of the empty span, so this is routed to unix, which

62+initial element of the empty span, so this is routed to Unix, which

61applies the effects.

63applies the effects.

63This is a call stack, with a crucial feature: the stack is a first-class

65This is a call stack, with a crucial feature: the stack is a first-class

@@ -90,42 +92,42 @@ caller.

90Vanes

92Vanes

91-----

93-----

93−As shown above, we use arvo proper to route and control the flow of

95+As shown above, we use Arvo proper to route and control the flow of

94−moves. However, arvo proper is rarely directly responsible for

96+moves. However, Arvo proper is rarely directly responsible for

95processing the event data that directly causes the desired outcome of a

97processing the event data that directly causes the desired outcome of a

96move. This event data is contained within a card, which is simply a

98move. This event data is contained within a card, which is simply a

97−`(pair term noun)`. Instead, arvo proper passes the card off to one of

99+`(pair term noun)`. Instead, Arvo proper passes the card off to one of

98its vanes, which each present an interface to clients for a particular

100its vanes, which each present an interface to clients for a particular

99well-defined, stable, and general-purpose piece of functionality.

101well-defined, stable, and general-purpose piece of functionality.

100

102

101As of this writing, we have seven vanes, which each provide the

103As of this writing, we have seven vanes, which each provide the

102following services:

104following services:

103

105

104−- `%ames` name of both our network and the vane that communicates over

106+- `%ames`: the name of both our network and the vane that communicates over

105− it

107+ it.

106−- `%behn` a simple timer

108+- `%behn`: a simple timer.

107−- `%clay` version-controlled, referentially- transparent, and global

109+- `%clay`: our version-controlled, referentially- transparent, and global

108− filesystem

110+ filesystem.

109−- `%dill` terminal driver. Unix sends keyboard events to `%dill` from

111+- `%dill`: a terminal driver. Unix sends keyboard events to `%dill` from

110 either the console or telnet, and `%dill` produces terminal output.

112 either the console or telnet, and `%dill` produces terminal output.

111−- `%eyre` http server. Unix sends http messages to `%eyre`, and

113+- `%eyre`: an http server. Unix sends http messages to `%eyre`, and

112− `%eyre` produces http messages in response

114+ `%eyre` produces http messages in response.

113−- `%ford` handles resources and publishing

115+- `%ford`: handles resources and publishing.

114−- `%gall` manages our userspace applications. `%gall` keeps state and

116+- `%gall`: manages our userspace applications. `%gall` keeps state and

115− manages subscribers

117+ manages subscribers.

116

118

117Cards

119Cards

118-----

120-----

119

121

120Cards are the vane-specific portion of a move. Each vane defines a

122Cards are the vane-specific portion of a move. Each vane defines a

121−protocol for interacting with other vanes (via arvo) by defining four

123+protocol for interacting with other vanes (via Arvo) by defining four

122types of cards: kisses, gifts, notes, and signs.

124types of cards: kisses, gifts, notes, and signs.

123

125

124−When one vane is `%pass`ed a card in its `++kiss`, arvo activates the

126+When one vane is `%pass`ed a card in its `++kiss`, Arvo activates the

125`++call` gate with the card as its argument. To produce a result, the

127`++call` gate with the card as its argument. To produce a result, the

126vane `%give`s one of the cards defined in its `++gift`. If the vane

128vane `%give`s one of the cards defined in its `++gift`. If the vane

127needs to request something of another vane, it `%pass`es it a `++note`

129needs to request something of another vane, it `%pass`es it a `++note`

128−card. When that other vane returns a result, arvo activates the `++take`

130+card. When that other vane returns a result, Arvo activates the `++take`

129gate of the initial vane with one of the cards defined in its `++sign`.

131gate of the initial vane with one of the cards defined in its `++sign`.

130

132

131In other words, there are only four ways of seeing a move: (1) as a

133In other words, there are only four ways of seeing a move: (1) as a

@@ -134,12 +136,12 @@ seen by the callee, a `++kiss`. (3) the response to that first request

134as seen by the callee, a `++gift`. (4) the response to the first request

136as seen by the callee, a `++gift`. (4) the response to the first request

135as seen by the caller, a `++sign`.

137as seen by the caller, a `++sign`.

136

138

137−When a `++kiss` card is passed to a vane, arvo calls its `++call` gate,

139+When a `++kiss` card is passed to a vane, Arvo calls its `++call` gate,

138passing it both the card and its duct. This gate must be defined in

140passing it both the card and its duct. This gate must be defined in

139every vane. It produces two things in the following order: a list of

141every vane. It produces two things in the following order: a list of

140−moves and a possibly-modified copy of its context. The moves are used to

142+moves and a possibly modified copy of its context. The moves are used to

141interact with other vanes, while the new context allows the vane to save

143interact with other vanes, while the new context allows the vane to save

142−its state. The next time arvo activates the vane it will have this

144+its state. The next time Arvo activates the vane it will have this

143context as its subject.

145context as its subject.

144

146

145This overview has detailed how to pass a card to a particular vane. To

147This overview has detailed how to pass a card to a particular vane. To

docs/arvo/internals/ford.md+3−3

@@ -10,7 +10,7 @@ sort: 6

10Our typed and marked computation engine.

12A variety of different services are provided by `%ford`, but they mostly

13−involve compiling hook files, slapping/slammming code with marked data,

13+involve compiling hook files, slapping/slamming code with marked data,

14and converting data between marks, including validating data to a mark.

15Throughout every computation, `%ford` keeps track of which resources are

16dependencies so that the client may be aware when one or more

@@ -99,12 +99,12 @@ functionality. We don't usually have naked hoods outside ford.

100### `%reef`

101

102−Produces a core containing the entirety of zuse and hoon, suitable for

102+Produces a core containing the entirety of Zuse and Hoon, suitable for

103running arbitrary code against. The mark is `%noun`.

104

105### `%ride`

106

107−Slaps a twig against a subject silk. The mark of the result is `%noun`.

107+Slaps a hoon against a subject silk. The mark of the result is `%noun`.

108

109### `%vale`

110

docs/arvo/internals/ford/commentary.md+62−62

@@ -43,7 +43,7 @@ number. Thus, the keys of `q.tad` are a subset of the numbers less than

43`jav` is the cache of previously-solved problems. The keys are a pair of

44a term (either `%hood`, `%slap`, or `%slam`) and a noun that represents

45the exact problem solved. In the case of a `%hood`, then, the key is of

46−the form `[%hood beam cage]`. For `%slap`, there is `[%slap vase twig]`.

46+the form `[%hood beam cage]`. For `%slap`, there is `[%slap vase hoon]`.

47For `%slam`, there is `[%slam vase vase]`. The values are the result of

48solving the problem. Note that this cache is wiped in `++stay` when ford

49is reloaded.

@@ -79,7 +79,7 @@ stored by index in `q.kig`, and the next available index is `p.kig`.

79 [%pact p=silk q=silk] :: patch

80 [%plan p=beam q=spur r=hood] :: structured assembly

81 [%reef ~] :: kernel reef

82− [%ride p=twig q=silk] :: silk thru twig

82+ [%ride p=hoon q=silk] :: silk thru hoon

83 [%vale p=mark q=ship r=*] :: validate [our his]

84 == ::

@@ -95,7 +95,7 @@ discussion of the public interface to ford below.

96 ++ calx :: concrete cache line

97 $% [%hood p=calm q=(pair beam cage) r=hood] :: compile

98− [%slap p=calm q=[p=vase q=twig] r=vase] :: compute

98+ [%slap p=calm q=[p=vase q=hoon] r=vase] :: compute

99 [%slam p=calm q=[p=vase q=vase] r=vase] :: compute

100 == ::

101

@@ -106,7 +106,7 @@ The input to a `%hood` is the location of the resource and a cage

106representing the data at that location. The output is the hood found by

107compiling the given cage at the given location.

108

109−The input to a `%slap` is the vase of the subject and the twig of the

109+The input to a `%slap` is the vase of the subject and the hoon of the

110formula against which we are slapping the subject. The output is the

111vase produced by slapping them.

112

@@ -158,7 +158,7 @@ subject of the body with a `=>`.

158different ways and may load resources from any location. These are

159placed in the subject of the body with a `=~`.

160

161−`src` is the set of twigs or references to twigs in the body of the

161+`src` is the set of hoons or references to hoons in the body of the

162program. Generally, each of these will represent a core, but this is not

163required. When compiling, these are strung together in a `=~`.

164

@@ -181,8 +181,8 @@ retrieve it from.

181### `++horn`

182

183 ++ horn :: resource tree

184− $% [%ape p=twig] :: /~ twig by hand

184+ $% [%ape p=hoon] :: /~ hoon by hand

185− [%arg p=twig] :: /$ argument

185+ [%arg p=hoon] :: /$ argument

186 [%day p=horn] :: /| list by @dr

187 [%dub p=term q=horn] :: /= apply face

188 [%fan p=(list horn)] :: /. list

@@ -191,7 +191,7 @@ retrieve it from.

191 [%man p=(map span horn)] :: /* hetero map

192 [%nap p=horn] :: /% homo map

193 [%now p=horn] :: /& list by @da

194− [%saw p=twig q=horn] :: /; operate on

194+ [%saw p=hoon q=horn] :: /; operate on

195 [%see p=beam q=horn] :: /: relative to

196 [%sic p=tile q=horn] :: /^ cast

197 [%toy p=mark] :: /mark/ static

@@ -202,7 +202,7 @@ discussion of their use from a user's perspective is documented in the [runes

202documentation](https://urbit.org/docs/arvo/internals/runes), so we will here

203only give a description of the data structure itself.

204

205−A `%ape` horn is simply a twig that gets evaluated and placed in the

205+A `%ape` horn is simply a hoon that gets evaluated and placed in the

206subject.

207

208A `%arg` is a gate that gets evaluated with a sample of our location and

@@ -232,7 +232,7 @@ with the same horn and is given a face according to its name.

232A `%now` is a horn that applies to each of a list of `@da`-named files

233in the directory.

234

235−A `%saw` is a twig and a horn, where the twig operates on the result of

235+A `%saw` is a hoon and a horn, where the hoon operates on the result of

236the horn.

237

238A `%see` is a beam and a horn, where the horn is evaluated at a location

@@ -246,7 +246,7 @@ A `%toy` is simply a mark to be baked.

246### `++hoop`, body

247

248 ++ hoop :: source in hood

249− $% [%& p=twig] :: direct twig

249+ $% [%& p=hoon] :: direct hoon

250 [%| p=beam] :: resource location

251 == ::

252

@@ -358,7 +358,7 @@ There are twelve possible computations defined in `++silk`.

358 [%mute p=silk q=(list (pair wing silk))] :: mutant

359 [%plan p=beam q=spur r=hood] :: structured assembly

360 [%reef ~] :: kernel reef

361− [%ride p=twig q=silk] :: silk thru twig

361+ [%ride p=hoon q=silk] :: silk thru hoon

362 [%vale p=mark q=ship r=*] :: validate [our his]

363 == ::

364

@@ -409,7 +409,7 @@ functionality. We don't usually have naked hoods outside ford.

409`%reef` produces a core containing the entirety of zuse and hoon,

410suitable for running arbitrary code against. The mark is `%noun`.

411

412−`%ride` slaps a twig against a subject silk. The mark of the result is

412+`%ride` slaps a hoon against a subject silk. The mark of the result is

413`%noun`.

414

415`%vale` validates untyped data from a ship against a given mark. This is

@@ -481,7 +481,7 @@ Fourth, we may have zero or more other `/` runes (as described in

481`++horn`), which represent program-specific resources to be loaded.

482

483Fifth and finally, we must have one or more body statements (hoops),

484−which are either direct twigs or `//` runes.

484+which are either direct hoons or `//` runes.

485

486 ++ hoot

487 ;~ pose

@@ -491,7 +491,7 @@ which are either direct twigs or `//` runes.

491

492A structure can either be a direct gate, or it can be a simple core.

493Either one is parsed with `++hoof`, so we distinguish the two cases by

494−requireing core references to be prefixed by a `*`.

494+requiring core references to be prefixed by a `*`.

495

496 ++ hoof

497 %+ cook |=(a=^hoof a)

@@ -529,10 +529,10 @@ parse, so we'll discuss those first.

529 (stag %& tall:vez)

530 ==

531

532−There are two types of hoops. Direct twigs are parsed with

532+There are two types of hoops. Direct hoons are parsed with

533−`++tall:vast`, which is the just the hoon parser for a tall-form twig.

533+`++tall:vast`, which is the just the Hoon parser for a tall-form rune.

534

535−References to external twigs are marked with a `//` rune followed by a

535+References to external hoons are marked with a `//` rune followed by a

536beam, which is parsed with `++have`.

537

538 ++ hath (sear plex:voz (stag %clsg poor:voz)) :: hood path

@@ -600,9 +600,9 @@ the wide form rule.

600 ;~(pfix gap tall:vez)

601

602`++ape:read` parses for both the `/~` and the `/$` runes. It produces a

603−twig. The wide form is a tuple of one or more ace-separated wide-form

603+hoon. The wide form is a tuple of one or more ace-separated wide-form

604−twigs parsed with `++wide:vast` and surrounded by `[` and `]`. The tall

604+hoons parsed with `++wide:vast` and surrounded by `[` and `]`. The tall

605−form is a single tall form twig parsed by `++tall:vast`

605+form is a single tall form hoon parsed by `++tall:vast`

606

607 ++ day

608 %+ rail

@@ -665,10 +665,10 @@ horn is inserted into the produced map as a key-value pair.

665 ;~(plug ;~(sfix wide:vez sem) apex(tol |))

666 ;~(pfix gap ;~(plug tall:vez ;~(pfix gap apex)))

667

668−This parses for the `/;` rune. It produces a twig and a horn. The wide

668+This parses for the `/;` rune. It produces a hoon and a horn. The wide

669−form is a wide-form twig followed by a `;` and, recursively, the entire

669+form is a wide-form hoon followed by a `;` and, recursively, the entire

670horn parser with tall form disabled. The tall form is a gap followed by

671−a tall-form twig, another gap, and, recursively, the entire horn parser.

671+a tall-form hoon, another gap, and, recursively, the entire horn parser.

672

673 ++ see

674 %+ rail

@@ -701,12 +701,12 @@ assembling is handled entirely within the `++meow:zo:za` core.

701

702 ++ meow :: assemble

703 |= [how=beam arg=heel]

704− =| $: rop=(map term (pair hoof twig)) :: structure/complex

704+ =| $: rop=(map term (pair hoof hoon)) :: structure/complex

705 zog=(set term) :: structure guard

706− bil=(map term (pair hoof twig)) :: libraries known

706+ bil=(map term (pair hoof hoon)) :: libraries known

707 lot=(list term) :: library stack

708 zeg=(set term) :: library guard

709− boy=(list twig) :: body stack

709+ boy=(list hoon) :: body stack

710 hol=? :: horns allowed?

711 ==

712 |%

@@ -715,7 +715,7 @@ We take two arguments and keep seven pieces of state. `how` is the

715location of the hook file we're assembling, and `arg` is the heel, or

716virtual path extension, of the file.

717

718−In `rop`, we maintain a map of terms to pairs of hooves and twigs to

718+In `rop`, we maintain a map of terms to pairs of hooves and hoons to

719represent the structures we've encountered that we will put together in

720a core at the top of the file.

721

@@ -724,7 +724,7 @@ loading. If we try to load a structure already in our dependency

724ancestry, then we fail because we do not allow circular dependencies.

725This enforces that our structure dependency graph is a DAG.

726

727−In `bil`, we maintain a map of terms to pairs of hooves and twigs to

727+In `bil`, we maintain a map of terms to pairs of hooves and hoons to

728represent the libraries we've encountered that we will put together in a

729series of cores after the structure core.

730

@@ -740,7 +740,7 @@ loading. If we try to load a library already in our dependency ancestry,

740then we fail because we do not allow circular dependencies. This

741enforces that our library dependency graph is a DAG.

742

743−In `boy`, we maintain a stack of body twigs, which we'll put together in

743+In `boy`, we maintain a stack of body hoons, which we'll put together in

744a series of cores at the end of the file.

745

746In `hol`, we decide if we're allowed to contain horns. Libraries and

@@ -823,7 +823,7 @@ this is that it does essentially five things.

823First, we call `++apex` to process the structures, libraries, and body.

824This changes our state, so we set our context to the produced context.

825Second, we call `++able` to assemble the strucutres and libraries into a

826−twig, which we slap against zuse with `++maim`. Third, we call `++chap`

826+hoon, which we slap against zuse with `++maim`. Third, we call `++chap`

827to process the resources in the context of the already-loaded structures

828and libraries. Fourth, we slap the body against the structures,

829libraries, and resources. Fifth and finally, we produce the resultant

@@ -916,7 +916,7 @@ individual hoop and recurse.

916 (fine cof sel(boy [[%brcn mav] boy]))

917 ==

918

919−In the case of a direct twig hoop, we just push it onto `boy` and we're

919+In the case of a direct hoon hoop, we just push it onto `boy` and we're

920done. In the case of an indirect hoop, we must compile the referenced

921file.

922

@@ -958,8 +958,8 @@ we are accumulating all the structures and libraries referenced in all

958the referenced hook files in one group, which we will put at the top of

959the product.

960

961−After this, we put the new list of body twigs into a `=~`, push this

961+After this, we put the new list of body hoons into a `=~`, push this

962−onto our old list of body twigs, and produce the result.

962+onto our old list of body hoons, and produce the result.

963

964If there is no hoon file here, then we descend into each of our children

965until we find a hoon file. First, we produce a list of all our children

@@ -986,8 +986,8 @@ those children whose names are not terms.

986Next, we will produce a map from terms to feet. Each of these feet will

987be placed in a core named by the child name, and it will contain arms

988according to its children. Thus, if the indirect hoop references

989−`/path`, then to access the twig defined in `/path/to/twig/hoon`, our

989+`/path`, then to access the hoon defined in `/path/to/hoon/hoon`, our

990−body must refer to `twig:to`.

990+body must refer to `hoon:to`.

991

992If there are no more children, then we are done, so we produce our

993current context.

@@ -1004,7 +1004,7 @@ We also produce the new context so that all external structures,

1004libraries, and resources are collected into the same place.

1005

1006Finally, we have a map of names to feet. If this map is empty, then

1007−there were no twigs at the requested path, so we give an error with

1007+there were no hoons at the requested path, so we give an error with

1008`++flaw`.

1009

1010If the map is nonempty, then we finally produce our context with with

@@ -1080,7 +1080,7 @@ that it takes a beam and parses the hook file there into a hood.

1080We recurse on this to compile the library. During the compilation, we

1081let `zeg` be `gez` to avoid circular dependencies, we let `hol` be false

1082since we don't allow horns in libraries, and we let `boy` be null so

1083−that we can isolate the new body twigs.

1083+that we can isolate the new body hoons.

1084

1085Next, we reintegrate the new data into our context. We use the context

1086created by the recursion with four changes. First, we reset `zeg` to our

@@ -1088,7 +1088,7 @@ old `zeg`. Second, we reset `hol` to our old `hol`. Third, we put the

1088name of our library onto the stack of libraries. This means all of a

1089libraries dependencies will be earlier in `lot` than the library itself,

1090making `lot` a topological ordering on the dependency graph. Fourth, we

1091−put in `bil` the library hoof and body (with all body twigs collected in

1091+put in `bil` the library hoof and body (with all body hoons collected in

1092a `=~`), keyed by the library name.

1093

1094Finally, we recurse, processing the next library in our list.

@@ -1135,7 +1135,7 @@ structures to process. If not, we're done, so we produce our context.

1135

1136Otherwise, we let `goz` be `zog` plus the current structure so that

1137while compiling the dependencies of this structure we don't later create

1138−a circular dependency. We check next to see if this structure is alredy

1138+a circular dependency. We check next to see if this structure is already

1139in `rop`. If so, then we have already included this structure earlier,

1140so we check to see if this is the same version of the structure as we

1141included earlier. If so, we skip it. Else, we fail since we can't

@@ -1147,19 +1147,19 @@ true, then we're looking for a gate; otherwise, we're looking for a

1147core. We parse this file with `++fade`.

1148

1149Now, we recurse on this to compile the structure. During the recursion,

1150−there we have threee changes. Frist, we let `zog` be `goz` so that we

1150+there we have three changes. Frist, we let `zog` be `goz` so that we

1151don't create a circular dependency. Second, we let `hol` be false since

1152we do not allow horns in structures. Third, we let `boy` be null so that

1153−we can isolate the new body twigs.

1153+we can isolate the new body hoons.

1154

1155Next, we reintegrate the new data into our context. We use the context

1156cretaed by the recursion with four changes. First, if we're including a

1157gate structure, then we reset the body to its original body. Else we put

1158−on the top of our list of body twigs what is essentially a

1158+on the top of our list of body hoons what is essentially a

1159`=+ structure-name` to take off the face of the structure. Second, we

1160reset `zog` to our old `zog`. Third, we reset `hol` to our old `hol`.

1161Finally, we put in `rop` the structure hoof and body (with all body

1162−twiggs collected in a `=~`), keyed by the structure name.

1162+hoongs collected in a `=~`), keyed by the structure name.

1163

1164Finally, we recurse, processing the next structure in our list.

1165

@@ -1180,13 +1180,13 @@ This concludes our discussion of `++apex`.

1180 (fine cof fin)

1181

1182Returning to `++abut`, we have now processed the structures, libraries

1183−and body twigs. Next, we slap our preamble (structures and libraries)

1183+and body hoons. Next, we slap our preamble (structures and libraries)

1184against zuse. First, we construct our preamble in `++able`.

1185

1186 ++ able :: assemble preamble

1187− ^- twig

1187+ ^- hoon

1188 :+ %tsgr

1189− ?:(=(~ rop) [%$ 1] [%brcn (~(run by rop) |=([* a=twig] [%ash a]))])

1189+ ?:(=(~ rop) [%$ 1] [%brcn (~(run by rop) |=([* a=hoon] [%ash a]))])

1190 [%tssg (turn (flop lot) |=(a=term q:(need (~(get by bil) a))))]

1191

1192We first put the structures in `rop` into a single `|%` at the top and

@@ -1197,10 +1197,10 @@ libraries are in consecutive cores.

1197We slap the preamble against zuse with `++maim`.

1198

1199 ++ maim :: slap

1200− |= [cof=cafe vax=vase gen=twig]

1200+ |= [cof=cafe vax=vase gen=hoon]

1201 ^- (bolt vase)

1202 %+ (clef %slap) (fine cof vax gen)

1203− |= [cof=cafe vax=vase gen=twig]

1203+ |= [cof=cafe vax=vase gen=hoon]

1204 =+ puz=(mule |.((~(mint ut p.vax) [%noun gen])))

1205 ?- -.puz

1206 | (flaw cof p.puz)

@@ -1215,7 +1215,7 @@ is not already in our cache. First we'll discuss the computation, then

1215we'll discuss the caching system.

1216

1217We call `++mule` with a call to `++mint:ut` on the type of our subject

1218−vase against the given twig. In other words, we're compiling the twig

1218+vase against the given hoon. In other words, we're compiling the hoon

1219with against the subject type in the given subject vase.

1220

1221If compilation fails, then we produce an error bolt with the produced

@@ -1343,14 +1343,14 @@ through them one by one.

1343 ?- -.hon

1344 %ape (maim cof bax p.hon)

1345

1346−This is `/~`. We slap the twig against our context.

1346+This is `/~`. We slap the hoon against our context.

1347

1348 %arg

1349 %+ cope (maim cof bax p.hon)

1350 |= [cof=cafe gat=vase]

1351 (maul cof gat !>([how arg]))

1352

1353−This is `/$`. We slap the twig against our context, which we expect to

1353+This is `/$`. We slap the hoon against our context, which we expect to

1354produce a gate. We slam this gate with a sample of `how` and `arg`,

1355which is our location and the heel (virtual path extension).

1356

@@ -1549,7 +1549,7 @@ This is `/:`. We process the given horn at the given beam.

1549 (maul cof gat sam)

1550

1551This is `/;`. First, we process the given horn. Then, we slap the given

1552−twig against our context to produce (hopefully) a gate. Finally, we slam

1552+hoon against our context to produce (hopefully) a gate. Finally, we slam

1553the vase we got from processing the horn against the gate.

1554

1555 %sic

@@ -1599,12 +1599,12 @@ We return once more to `++abut`.

1599 |= [cof=cafe gox=vase]

1600 %+ cope (maim cof (slop gox bax) [%tssg (flop boy)])

1601 |= [cof=cafe fin=vase]

1602− (fine cof fin)

1602+ (fine cof fin)

1603

1604Recall that we processed our structures, libraries and body with

1605`++apex`. We slapped our structures and libraries against zuse with

1606`++maim`. We processed our resources with `++chap`. Now, all our body

1607−twigs are collected in a `=~` and slapped against our structures,

1607+hoons are collected in a `=~` and slapped against our structures,

1608libraries, and resources. This produces our final result.

1609

1610The hook file has been assembled. And there was great rejoicing.

@@ -2346,23 +2346,23 @@ of the main silk, so we mark the produced vase with the original mark.

2346 ++ keel :: apply mutations

2347 |= [cof=cafe suh=vase yom=(list (pair wing vase))]

2348 ^- (bolt vase)

2349− %^ maim cof

2349+ %^ maim cof

2350 %+ slop suh

2351 |- ^- vase

2352 ?~ yom [[%atom %n] ~]

2353 (slop q.i.yom $(yom t.yom))

2354− ^- twig

2354+ ^- hoon

2355 :+ %cncb [%& 2]~

2356 =+ axe=3

2357− |- ^- (list (pair wing twig))

2357+ |- ^- (list (pair wing hoon))

2358 ?~ yom ~

2359 :- [p.i.yom [%$ (peg axe 2)]]

2360 $(yom t.yom, axe (peg axe 3))

2361

2362We first put the vases together in one big tuple starting with the

2363subject and going through the mutations. We slap against this tuple a

2364−`%_` twig we directly construct. Since a `%_` twig takes a list of pairs

2364+`%_` hoon we directly construct. Since a `%_` hoon takes a list of pairs

2365−of wings and twigs, we simply have to generate twigs referring to the

2365+of wings and hoons, we simply have to generate hoons referring to the

2366correct axes in the subject. This is very easy since we just recur on

2367axis 3 of whatever axis we were already at.

2368

@@ -2483,7 +2483,7 @@ Lifcycle of a `%ride`

2483 (fine cof %noun vax)

2484

2485This slaps evaluates the given silk, then it slaps the result against

2486−the given twig. Since we don't know what of what mark (if any) is the

2486+the given hoon. Since we don't know what of what mark (if any) is the

2487result, we give it a mark of `%noun`.

2488

2489Lifecycle of a `%vale`

@@ -2532,7 +2532,7 @@ At any rate, `++lake` coerces a noun into the correct type for a mark.

2532 (flaw cof [%leaf "ford: no noun: {<[for bek]>}"]~)

2533 %+ cope (maul cof (slap gab [%cnzy %noun]) [%noun q.sam])

2534 |= [cof=cafe pro=vase]

2535− ?: =(+<.q.pro q.sam)

2535+ ?: =(+<.q.pro q.sam)

2536 (fine cof (slot 6 pro))

2537 (flaw cof [%leaf "ford: invalid content: {<[for bek]>}"]~)

2538

docs/arvo/subscriptions.md+26−26

@@ -11,11 +11,11 @@ We've dealt fairly extensively with "poke" messages to an app, but these

11are somewhat limited. A poke is a one-way message, but more often we

12want to subscribe to updates from another app. You could build a

13subscription model out of one-way pokes, but it's such a common pattern

14−that it's built into arvo.

14+that it's built into Arvo.

16Let's take a look at two apps, `:source` and `:sink`. First,

17`:source`:

18−

18+

19 :: Sends subscription updates to sink.hoon

20 ::

21 :::: /===/app/source/hoon

@@ -69,7 +69,7 @@ Let's take a look at two apps, `:source` and `:sink`. First,

69 --

71And secondly, `:sink`:

72−

72+

73 :: Sets up a simple subscription to source.hoon

74 ::

75 :::: /===/app/sink/hoon

@@ -137,43 +137,43 @@ Cheat sheet:

137

138- `&` (pam) can either be the boolean true (as can `%.y`, `0`), or

139 the irregular wide form of the `?&`

140− ([wutpam](../../hoon/twig/wut-test/pam-and)) rune, which computes

140+ ([wutpam](../../hoon/rune/wut/pam)) rune, which computes

141 logical `AND` on its two children.

142

143- Similar to `&`,`|` is either the boolean false (along with `%.n` and

144 `1`), or the irregular short for of `?|`

145− ([wutbar](../../hoon/twig/wut-test/bar-or)), which computes logical `OR`

145+ ([wutbar](../../hoon/rune/wut/bar)), which computes logical `OR`

146 on its two children.

147

148- `!` is the irregular wide form of `?!`

149− ([wutzap](../../hoon/twig/wut-test/zap-not/)), which computes logical

149+ ([wutzap](../../hoon/rune/wut/zap/)), which computes logical

150 `NOT` on its child.

151

152−- `?~` ([wutsig](../../hoon/twig/wut-test/sig-ifno/)) is basically an

152+- `?~` ([wutsig](../../hoon/rune/wut/sig/)) is basically an

153 if-then-else that checks whether condition `p` is `~` (null). `?~`

154 is slightly different from `?:(~ %tru %fal)` in that `?~` reduces to

155 `?:($=(%type value) %tru %false)`. `$=`

156− ([buctis](../../hoon/twig/buc-mold/tis-coat/)) tests whether value `q` is

156+ ([buctis](../../hoon/rune/buc/tis/)) tests whether value `q` is

157 of type `p`.

158−<!-- One thing to watch out for in hoon: if you do `?~`, it

158+<!-- One thing to watch out for in Hoon: if you do `?~`, it

159 affects the type of the conditional value: XXexample -->

160

161−- `:_` ([colcab](../../hoon/twig/col-cell/cab-scon/)) is inverted `:-`: it

161+- `:_` ([colcab](../../hoon/rune/col/cab/)) is inverted `:-`: it

162 accepts `p` and `q`, and produces `[q p]`.

163

164- `++bowl` is the type of the system state within our app. For

165 example, it includes things like `our`, the name of the host urbit,

166 and `now`, the current time.

167

168−- `$%` ([buccen](../../hoon/twig/buc-mold/cen-book/)) is a type

168+- `$%` ([buccen](../../hoon/rune/buc/cen/)) is a type

169 constructor: it defines a new type, composed of `n` types that it is

170 passed. For example `$% @ * ^ ==` is the type of either `@`,

171 `*`, or a cell `^`.

172

173

174- You may have noticed the separate `|%`

175− ([barcen](../../hoon/twig/bar-core/cen-core/)) above the application core

175+ ([barcen](../../hoon/rune/bar/cen/)) above the application core

176− `|_` ([barcab](../../hoon/twig/bar-core/cab-door/). We usually put our

176+ `|_` ([barcab](../../hoon/rune/bar/cab/). We usually put our

177 types in another core on top of the application core. We can access

178 these type from our `|_` because in `hoon.hoon` files, all cores are

179 called against each other. (The shorthand for 'called' is `=>`.)

@@ -232,8 +232,8 @@ added to it. This is why no wire is needed for the move -- we won't

232receive anything in response to it.

233

234Anyways, there are four functions (arms) inside the `|_`. We already know when

235−`++poke-noun` is called. `++peer-example-path` is called when someone tries to

235+`++poke-noun` is called. `++peer-example-path` is called when someone tries to

236−subscribe to our app. Of course, you don't just subscribe to an app; you

236+subscribe to our app. Of course, you don't just subscribe to an app; you

237subscribe to a path on that app. This path comes in as the argument to `++peer`.

238

239In our case, we don't care what path you subscribed on, and all we do is print

@@ -254,8 +254,8 @@ languages call "map" -- it runs a function on every item in a list and collects

254the results in a list. The list is `(prey /example-path bow)` and the function

255is the `|=` line right after it.

256

257−`++prey` is a standard library function defined in `zuse.hoon`. It takes a path

257+`++prey` is a standard library function defined in `zuse.hoon`. It takes a path

258−and a bowl and gives you a list of the subscribers who are subscribed on a path

258+and a bowl and gives you a list of the subscribers who are subscribed on a path

259that begins with the given path. "Prey" is short for "prefix".

260

261Now we have the list of relevant subscribers. This a list of triples,

@@ -268,7 +268,7 @@ straightforward!

268

269### :sink

270

271−`:source` should now make sense. `:sink` is a little longer, but not much more

271+`:source` should now make sense. `:sink` is a little longer, but not much more

272complicated.

273

274In `:sink`, our definition of of `++move` is different. All moves start

@@ -290,7 +290,7 @@ is the sign of type boolean (similar to `*`, `@`), which defaults to true (that

290is, `0`).

291

292In `++poke-noun` we check our input to see both if it's `%on` and we're

293−available (`val` is true). If so, we produce the move to subscribe to

293+available (`val` is true). If so, we produce the move to subscribe to

294`:source`:

295

296 :~ :* ost.bow

@@ -301,15 +301,15 @@ available (`val` is true). If so, we produce the move to subscribe to

301 ==

302 ==

303

304−Also, in the preceding lines, we set `val` to false (`|`) with `+>.$(val |)`.

304+Also, in the preceding lines, we set `val` to false (`|`) with `+>.$(val |)`.

305−Remember that the `:_` constructs an inverted cell, with the first child

305+Remember that the `:_` constructs an inverted cell, with the first child

306−(`+>.$(val |` in our case) as the tail and the second child as the head. Here,

306+(`+>.$(val |` in our case) as the tail and the second child as the head. Here,

307−the cell we produce when our subscription is `%on` and `val` is true has a

307+the cell we produce when our subscription is `%on` and `val` is true has a

308−head with our new state where `val` is set to false and a tail of our list of

308+head with our new state where `val` is set to false and a tail of our list of

309moves, which is shown in the code block above.

310

311Otherwise, if our input is `%off` and we're already subscribed (i.e. `val`

312−is false), then we unsubscribe from `:source` and set `val` back to true (`&`),

312+is false), then we unsubscribe from `:source` and set `val` back to true (`&`),

313again using our handy inverted cell constructor mold `:_`:

314

315 :_ +>.$(val &)

@@ -319,7 +319,7 @@ It's important to send over the same bone and wire (`/subscribe`) as the

319one we originally subscribed on.

320

321If neither of these cases are true, then we print our current subscription

322−state, based on whether `val` is true or false, and return a cell containing

322+state, based on whether `val` is true or false, and return a cell containing

323a null list of moves and our unchanged app state:

324

325 ~& ?: val

docs/hall/architecture.md+18−15

@@ -28,9 +28,9 @@ Hall's implementation is structured according to the new Gall model. Familiarity

28 * [Interactions](#interactions)

29 * [Queries, prizes and rumors](#queries-prizes-and-rumors)

30* [Communication between Halls](#communication-between-halls)

31− * [Interactions](#interactions-1)

31+ * [Commands](#commands)

32 * [Querying](#querying)

33− * [Federation](#federation)

33+ * [Federation implementation](#federation-implementation)

34* [Hall implementation](#hall-implementation)

35 * [Subscriptions](#subscriptions)

36 * [Rumors](#rumors)

@@ -42,9 +42,9 @@ Hall's implementation is structured according to the new Gall model. Familiarity

43## Introduction

45−Talk was Urbit's first big user-facing application. It continues to enjoy a prominent role in the Urbit landscape, but does so as two separate applications this time.

45+Talk was Urbit's first big user-facing application. It continues to enjoy a prominent role in the Urbit landscape, but now does so as two separate applications.

47−The messaging parts of Talk have been separated from its user interface parts. What we ended up with is a shiny new generic messaging bus, and the chat interface we all know and love. The messaging bus, which should now prove useful to many different applications, will be named `Hall`. Applications that use it are referred to as *clients*. One such application, as you might have guessed, is `Talk`.

47+The messaging parts of Talk have been separated from its user-interface parts. What we ended up with is a shiny new generic messaging bus, and the chat interface we all know and love. The messaging bus, which should now prove useful to many different applications, will be named `Hall`. Applications that use it are referred to as *clients*. One such application, as you might have guessed, is `:talk`.

50## Structures & functionality

@@ -117,6 +117,7 @@ Messages aren't the only thing a subscription gets us. We're also kept up to dat

117```

118

119`status` is user-set metadata that describes, well, the status of users in a circle. This encompasses their `presence`, which shows their activity, and their `human` identity, which includes their display handle.

120+

120For reasons we'll discover shortly, circles keep track of both their own `group` and those of the circles they're subscribed to. `crowd` encapsulates this.

121For reasons we'll discover shortly, circles keep track of both their own `group` and those of the circles they're subscribed to. `crowd` encapsulates this.

121

122

122### Configurations

123### Configurations

@@ -191,9 +192,10 @@ As an example, Talk operates like this, serving as an interface for reading from

191

192

192### Federation

193### Federation

193

194

194−Some places, like `urbit-meta`, will want to be easily accessible to everyone on the network, and actually support the load that comes with that. Both these desired can be met through federation.

195+Some places, like `urbit-meta`, will want to be easily accessible to everyone on the network, and actually support the load that comes with that. Both of these desires can be achieved through federation.

196+

197+With federation, stories and any changes to them trickle down from ~zod, to other galaxies, to their stars. Only changes to messages and presence can also move upstream, from stars, to galaxies, to ~zod (and then back down again).

195

198

196−In federation, stories and any changes to them trickle down from ~zod, to other galaxies, to their stars. Only changes to messages and presence can also move upstream, from stars, to galaxies, to ~zod (and then back down again).

197This way, all planets and comets will be able to subscribe to `/urbit-meta` (that is, the `urbit-meta` circle on their parent ship) and get all updates on the story, regardless of where on the network they originated.

199This way, all planets and comets will be able to subscribe to `/urbit-meta` (that is, the `urbit-meta` circle on their parent ship) and get all updates on the story, regardless of where on the network they originated.

198

200

199### Public membership

201### Public membership

@@ -286,6 +288,7 @@ To receive data from Hall, applications will have to query it. There are two pat

286```

288```

287

289

288To be clear, the paths for those queries are `/client` and `/circle/[name]/[data]/[start]/[end]`, where data is at least one `circle-data`, and `start` and `end` are optional and can be either a date or a message number.

290To be clear, the paths for those queries are `/client` and `/circle/[name]/[data]/[start]/[end]`, where data is at least one `circle-data`, and `start` and `end` are optional and can be either a date or a message number.

291+

289`/client` queries produce shared UI state. That is, glyph bindings and nicknames.

292`/client` queries produce shared UI state. That is, glyph bindings and nicknames.

290`/circle` queries produce the entire public state of the requested story, including remotes.

293`/circle` queries produce the entire public state of the requested story, including remotes.

291

294

@@ -341,9 +344,9 @@ These are, as enforced by Gall, the changes as they happen. This makes it possib

341

344

342## Communication between Halls

345## Communication between Halls

343

346

344−Halls can communicate with other Halls to send commands and subscription updates.

347+Halls can communicate with other Halls by sending commands and subscription updates.

345

348

346−### Interactions

349+### Commands

347

350

348To request changes to a story, Halls can send `command`s.

351To request changes to a story, Halls can send `command`s.

349

352

@@ -373,11 +376,12 @@ Halls can query other halls. Here's the peer move we send when we open a query o

373```

376```

374

377

375Again, the rumor path is what our Hall uses to identify what query a received message originates from. Our circle is specified so that we know what story is interested in the changes we get.

378Again, the rumor path is what our Hall uses to identify what query a received message originates from. Our circle is specified so that we know what story is interested in the changes we get.

379+

376The query path is slightly more interesting. Of course it specifies the name of their story we want to subscribe our story to, but also a "start" and "end". These can (optionally) be used to specify the range of messages we want to get from our query. Once that range has passed, we stop receiving updates.

380The query path is slightly more interesting. Of course it specifies the name of their story we want to subscribe our story to, but also a "start" and "end". These can (optionally) be used to specify the range of messages we want to get from our query. Once that range has passed, we stop receiving updates.

377

381

378−### Federation

382+### Federation implementation

379

383

380−Along the way so far, we've skipped some parts of structures. Most of these relate to federation. Let's see what we missed.

384+Along the way so far, we've skipped some parts of structures. Most of those relate to federation. Let's see what we missed.

381

385

382```

386```

383++ query :> query paths

387++ query :> query paths

@@ -496,22 +500,21 @@ Hall is neither complete nor perfect. There are features that need to be impleme

496

500

497To turn Talk into a [sustainable social platform](https://urbit.org/fora/posts/~2017.4.26..18.00.25..b93c~/), it needs a number of things.

501To turn Talk into a [sustainable social platform](https://urbit.org/fora/posts/~2017.4.26..18.00.25..b93c~/), it needs a number of things.

498

502

499−Primarily, discoverability of circles. A possible solution for realizing this is making it possible for users to add friends, which would have their Hall subscribe to a list of circles the added friends are in. The existing public membership functionality can be leveraged for this.

503+We want to have some kind of discoverability for circles. This could be realized by making it possible for users to add friends, who would have their Hall subscribe to a list of circles the added friends are in. The existing public membership functionality can be leveraged for this.

500

504

501Eventually, content self-moderation might need to be implemented. Users would flag their content if it is potentially offensive. Others would easily be able to filter out content that might offend them.

505Eventually, content self-moderation might need to be implemented. Users would flag their content if it is potentially offensive. Others would easily be able to filter out content that might offend them.

502This functionality brings its own large sets of challenges that need to be tackled.

506This functionality brings its own large sets of challenges that need to be tackled.

503

507

504−Additionally, federation might be put to broader use. Knowing a circle is federated could help fall back to alternative hosts in case the one Hall originally subscribed to is unavailable.

508+Additionally, federation might be put to broader use. Knowing that a circle is federated could help fall back to alternative hosts in case the one Hall originally subscribed to is unavailable. Implementation-wise, care would need to be taken for this to not get ugly. Not to mention, when/how would availability of a host be verified?

505−Implementation-wise, care would need to be taken for this to not get ugly. Not to mention, when/how would availability of a host be verified?

506

509

507Other changes that might have a fair impact on the functioning of Hall are un/read states for messages, and being able to use moons to allow your friends to chat with you in a local channel.

510Other changes that might have a fair impact on the functioning of Hall are un/read states for messages, and being able to use moons to allow your friends to chat with you in a local channel.

508

511

509−Smaller functionality that still needs to be implemented includes:

512+More minor functionalities that need to be implemented include:

510* Extended permissions management. Being able to black-/whitelist entire ship classes.

513* Extended permissions management. Being able to black-/whitelist entire ship classes.

511* Improved presence functionality. Actually using the presence system, and sending "typing", "idle", etc. statuses.

514* Improved presence functionality. Actually using the presence system, and sending "typing", "idle", etc. statuses.

512* Polls.

515* Polls.

513

516

514−And of course there's a lot Talk, the client, can improve on as well.

517+And, of course, there's a lot that the Talk client can improve on as well.

515

518

516

519

517## Further reading

520## Further reading

docs/hall/interface.md+6−5

@@ -60,7 +60,7 @@ Valid paths include:

61#### /client prize

63−Contains a map of glyphs and the audiences they map to, as well as a map of ships and their locally set nicknames.

63+Contains a map of glyphs and the audiences that they map to, as well as a map of ships and their locally set nicknames.

65```

66++ prize :> query result

@@ -133,7 +133,7 @@ Contains a circle that was either added or removed from the public list.

133

134### /peers

135

136−To allow a circle owner to inspect who is actually currently subscribed to their stories, they can issue a query to retrieve subscription data.

136+To allow a circle owner to inspect who is currently subscribed to their stories, they can issue a query to retrieve subscription data.

137

138```

139++ query ::

@@ -181,6 +181,7 @@ Contains a ship and a query, and a flag to indicate whether that subscription ha

181

182Circle queries allow for the retrieving of data from stories. Their messages, configuration, and presences can all be accessed. Since this is a lot of data, there are lots of possibilities for filtering it built in to the query itself.

183

184+

184A quick refresher on the difference between "local" and "remote" presence and configuration: "local" means it pertains to the circle itself; "remote" means it pertains to one of its configured sources. The latter is primarily useful to clients when using a circle for aggregation, like the `%inbox`.

185A quick refresher on the difference between "local" and "remote" presence and configuration: "local" means it pertains to the circle itself; "remote" means it pertains to one of its configured sources. The latter is primarily useful to clients when using a circle for aggregation, like the `%inbox`.

185

186

186```

187```

@@ -262,8 +263,8 @@ Contains (where applicable) messages in envelopes (with message numbers), as wel

262#### /circle rumor

263#### /circle rumor

263

264

264Contains a detailed change description of the data relevant to the query that changed.

265Contains a detailed change description of the data relevant to the query that changed.

266+

265−Messages are wrapped in envelopes to include their sequence number, and note the source they were heard from.

267+Messages are wrapped in envelopes to include their sequence number, and note the source they were heard from. Configuration and status changes specify the circle they apply to.

266−Configuration and status changes specify the circle they apply to.

267

268

268```

269```

269++ rumor :> query result change

270++ rumor :> query result change

@@ -334,7 +335,7 @@ Since all of these apply to a specific circle, they all specify a name `nom` of

334

335

335### Messaging

336### Messaging

336

337

337−There are two interfaces for telling hall to send a message. The first takes entire `thought`s, the second only `speech`es and the audience to send them to.

338+There are two interfaces for telling Hall to send a message. The first takes entire `thought`s, the second only `speech`es and the audience to send them to.

338

339

339```

340```

340++ action :> user action

341++ action :> user action

docs/hall/new-gall.md+25−23

@@ -9,7 +9,7 @@ title: The new Gall model

10This document is complemented by the source code of applications that use the new Gall model (like [Hall](https://github.com/urbit/arvo/blob/master/app/hall.hoon)), but doesn't require it. Code snippets will be provided where useful. Some knowledge of Hoon and the functioning of Hoon apps is assumed.

12−New Gall has not yet fully solidified. As such, structure and naming are tentative to change.

12+New `%gall` has not yet fully solidified. As such, its structure and naming are tentative.

14## Table of contents

@@ -30,7 +30,8 @@ New Gall has not yet fully solidified. As such, structure and naming are tentati

30## Renewing a pillar of Arvo

32When you write an app, Gall is responsible for making sure its event arms like `++poke` get called when they need to. In essence, it provides developers with a consistent interface for hooking their app up to the operating system.

33+

33−It's not doing a lot to make sure this is done in a structured way though, which results in apps (especially larger ones) feeling like big tangled messes. Something needs to be done about this.

34+It's not doing a lot to make sure this is done in a structured way, though, which results in apps (especially larger ones) feeling like big, tangled messes. Something needs to be done about this.

35### Problems

36### Problems

@@ -39,7 +40,8 @@ Imagine a `++poke`, `++diff`, or even a `++peer` arm. In current implementations

39Or (sadly) more commonly:

40Or (sadly) more commonly:

40`^- {(list move) _+>.$}`

41`^- {(list move) _+>.$}`

42−These arms are producing both side-effects and new state. To do this, their code has to simultaneously figure out "how does this poke/diff/whatever change our state?" and "what side-effects does this change have?".

43+These arms are producing both side-effects and new state. To do this, their code has to simultaneously figure out "how does this poke/diff/whatever change our state?" and "what side-effects does this change have?"

44+

43You'll find that the logic relating to these two often becomes tangled, making the flow of the whole more difficult to understand. And the side-effects more often than not relate to subscriptions, for which the developer may be writing a lot of boilerplate code. Gall currently does not help in either of these places.

45You'll find that the logic relating to these two often becomes tangled, making the flow of the whole more difficult to understand. And the side-effects more often than not relate to subscriptions, for which the developer may be writing a lot of boilerplate code. Gall currently does not help in either of these places.

45> The main significant cost of software development is the cost of

47> The main significant cost of software development is the cost of

@@ -51,27 +53,26 @@ cost is extremely welcome.

52### Solutions

54### Solutions

54−Let's imagine a world in which Gall *does* help, in both those places.

56+Let's imagine a world in which Gall *does* help, in both of those places.

57+

58+It would be wonderful if Gall could take care of all standard subscription management logic for you, and direct the flow of code as it concludes is appropriate. Applications, then, would have to help Gall by providing the different parts of this flow, and providing the checks that allow Gall to make the right decisions. This takes some work out of the developer's hands and results in more structured application code.

59+

60+If we expand on that a bit, then we can even have Gall help us in untangling state changes from side effects. We do so by separating state changes into two phases: *analyzing* what changes need to be made, and *applying* those changes.

56−It would be wonderful if Gall could take care of all standard subscription management logic for you, and direct the flow of code as it concludes is appropriate.

62+But where do the side-effects go, then? We need to realize there's two kinds: side-effects that are subscription updates, and side-effects that aren't. The latter get produces by applying state changes, while the former get integrated into the Gall flow we described above.

57−Applications, then, would have to help Gall by providing the different parts of this flow, and the checks that allow Gall to make the right decisions. This takes some work out of the developer's hands and results in more structured application code.

59−If we expand on that a bit we can even have Gall help us in untangling state changes from side effects. We do so by separating state changes into two phases: *analyzing* what changes need to be made, and *applying* those changes.

60−But where do the side-effects go then? We need to realize there's two kinds: side-effects that are subscription updates, and those that aren't. The latter get produces by applying state changes, while the former get integrated into the Gall flow we described above.

61−Since subscriptions are essentially queries to an app, requesting a specific part of its data/state, we can deduce subscription updates from state changes. We merely provide the logic, and Gall chains it all together.

64+Since subscriptions are essentially queries to an app, requesting a specific part of its data/state, we can deduce subscription updates from state changes. We merely provide the logic, and Gall chains it all together. Having Gall support all this allows us to cleanly and structurally untangle state change analysis, application, and subscription logic into their own arms.

63−Having Gall support all this allows us to cleanly and structurally untangle state change analysis, application, and subscription logic into their own arms.

64−For trivial apps, this might result in some arms with trivial code. Though it may feel like writing cruft, it makes understanding the app just as simple as it actually as.

65−For more complex apps, all logic is no longer a big chunk of "what do we do when x happens?", but rather a couple of smaller chunks, like "x happened, how does that change our state?" and "if our state changes like y, what does that mean for subscription z?" These are precisely the kinds of questions that application developers should be asked.

66+For trivial apps, this might result in some arms with trivial code. Though it may feel like writing cruft, it makes understanding the app just as simple as it actually as. For more complex apps, all logic is no longer a big chunk of "what do we do when x happens?" Rather, it's a few smaller chunks, like "x happened, how does that change our state?" and "if our state changes like y, what does that mean for subscription z?" These are precisely the kinds of questions that application developers should be asked.

68## As seen in new Gall

69## As seen in new Gall

70−Of course for the above to be made into reality, Gall will need to see some changes. Let's outline the new structures and the arms they get passed between.

71+Of course, for the above to be made into reality, Gall will need to see some changes. Let's outline the new structures and the arms they get passed between.

72### Structures

73### Structures

74−This wouldn't be Urbit if we had some cool new terminology for people to learn. These ones are (for the most part) semantically sensible though, and you might already see how these relate to the story above.

75+This wouldn't be Urbit if we didn't have cool terminology for people to learn. These ones are (for the most part) semantically sensible, and you might already see how they relate to the story above.

76`brain`: application state.

77`brain`: application state.

77`delta`: change to application state.

78`delta`: change to application state.

@@ -97,11 +98,13 @@ This also wouldn't be Urbit if we couldn't boil that down to a few simple pseudo

97 (gain rumor:(feel query delta) prize:(peek brain query))

98 (gain rumor:(feel query delta) prize:(peek brain query))

98```

99```

100

100−There, in the first three arms we already have the bulk of new Gall! `++gain` won't be part of it, since most applications don't need to keep track of `prize`s directly. Those that do may still implement and hook it up themselves though.

101+There. In the first three arms we already have the bulk of new Gall! `++gain` won't be part of it, since most applications don't need to keep track of `prize`s directly. Those that do may still implement and hook it up themselves though.

101

102

102Of course, these aren't all of the new Gall arms. Most important to still mention is `++leak`, which takes a `ship` and `query` and checks if the former has permission to ask for the latter.

103Of course, these aren't all of the new Gall arms. Most important to still mention is `++leak`, which takes a `ship` and `query` and checks if the former has permission to ask for the latter.

104+

103−There's also `++look` for asynchronous reads, `++hear` for subscription updates (rumors), `++fail` for dealing with process errors, `++cope` for dealing with transaction results, and `++pour` for dealing with responses from arvo.

105+There's also `++look` for asynchronous reads, `++hear` for subscription updates (rumors), `++fail` for dealing with process errors, `++cope` for dealing with transaction results, and `++pour` for dealing with responses from Arvo.

104`++prep`, `++poke` and `++pull` continue to function as they do right now.

106`++prep`, `++poke` and `++pull` continue to function as they do right now.

107+

105For a more verbose specification of all of these, see the new Gall spec.

108For a more verbose specification of all of these, see the new Gall spec.

106

109

107

110

@@ -160,7 +163,7 @@ Now, let's implement all the arms that will be called as things start happening.

160 & :: everyone's allowed

163 & :: everyone's allowed

161```

164```

162

165

163−Next, let's create the `prize`s for the folks that make it through `++leak`. We'll be producing a `(unit (unit prize))` so we can potentially say `~` for "unavailable" and `[~ ~]` for "invalid query".

166+Next, let's create the `prize`s for the folks that make it through `++leak`. We'll be producing a `(unit (unit prize))` so we can potentially say `~` for "unavailable" and `[~ ~]` for "invalid query."

164

167

165```

168```

166++ peek :> synchronous read

169++ peek :> synchronous read

@@ -173,9 +176,10 @@ Next, let's create the `prize`s for the folks that make it through `++leak`. We'

173 ==

176 ==

174```

177```

175

178

179+

176### Updating state & query results

180### Updating state & query results

177

181

178−Our app can get queried! If they're interested enough, they'll want to receive updates on that whenever relevant state changes. First, let's see how state changes happen. We still have regular old `++poke` arms, let's use that to prompt our application to change its state.

182+Our app can be queried! If they're interested enough, they'll want to receive updates on that whenever relevant state changes. First, let's see how state changes happen. We still have regular old `++poke` arms, let's use that to prompt our application to change its state.

179

183

180```

184```

181++ poke-loob :> regular old poke

185++ poke-loob :> regular old poke

@@ -231,13 +235,11 @@ As we saw earlier, for `/number` queries the `delta`s match one-on-one with the

231

235

232## Criticism

236## Criticism

233

237

234−* Where event arms currently get passed a `wire`, and the new Gall described above passes them a custom `query` structure, the original new Gall spec gave them `(list coin)`, a "pre-parsed wire". These structures (eg `[%$ p=[p=~.ud q=123]]`) are uncomfortable to work with. Even with a "coin list parsing library" it still doesn't feel ideal.

238+* Where event arms currently get passed a `wire`, and the new Gall described above passes them a custom `query` structure, the original new Gall spec gave them `(list coin)`, a "pre-parsed wire". These structures (eg `[%$ p=[p=~.ud q=123]]`) are uncomfortable to work with. Even with a "coin list parsing library" it still doesn't feel ideal. Because of custom structures being easier to work with than lists of `++knot`s or `++coin`s, writing a `++path-to-query` arm by hand is a small cost for huge gains.

235−Because of custom structures being easier to work with than lists of knots or coins, writing a `++path-to-query` arm by hand is a small cost for huge gains.

236

239

237−* Why do `prize` units mean what they do? Would have expected `~` to mean "invalid" and `[~ ~]` to mean "unavailable" as opposed to the other way around.

240+* Why do `prize` units mean what they do? One would expect `~` to mean "invalid" and `[~ ~]` to mean "unavailable" as opposed to the other way around.

238

241

239−* The original new Gall spec mentions output lists (like `(list delta)` etc.) to be in reverse order. This was done because adding to the head of a list (`[item list]`) is easier than appending to the tail of a list (`(weld list [item ~])` or other).

240−While it's technically easier to produce a list in reverse order, semantically it's yet another thing to keep in mind. Luckily, most of the "add to x, produce all of it later" code is set-and-forget, so probably not a huge deal, but do we really fear a few stray `++flop`s that much?

242+* The original new Gall spec mentions output lists (like `(list delta)` etc.) to be in reverse order. This was done because adding to the head of a list (`[item list]`) is easier than appending to the tail of a list (`(weld list [item ~])` or other). While it's technically easier to produce a list in reverse order, semantically it's yet another thing to keep in mind. Luckily, most of the "add to x, produce all of it later" code is set-and-forget, so probably not a huge deal. But do we really fear a few stray `++flop`s that much?

241

243

242* There's some weirdness with relation to relying on old state in `++feel` to determine whether a query result actually changed. Just relying on state in general for delta-to-rumor conversion may or may not violate the new Gall spec.

244* There's some weirdness with relation to relying on old state in `++feel` to determine whether a query result actually changed. Just relying on state in general for delta-to-rumor conversion may or may not violate the new Gall spec.

243

245

docs/hoon/cheat-sheet.md+5−6

@@ -1,6 +1,5 @@

1---

2navhome: /docs/

3−next: true

4sort: 26

3sort: 26

5title: Cheat sheet

4title: Cheat sheet

6---

5---

@@ -16,12 +15,12 @@ _Original Fora post_ [*here*](https://urbit.org/fora/posts/~2017.9.18..22.31.06.

17<br />

16<br />

19−We've found it's useful to have a quick reference of Hoon's syntax always at

18+We've found it's useful to have a quick reference of Hoon's syntax always at

20−hand. So above is a download link to a Hoon cheatsheet .pdf. It's missing a

19+hand. So above is a download link to a Hoon cheatsheet .pdf. It's missing a

21−few of the literal syntaxes, but it covers the most common ones.

20+few of the literal syntaxes, but it covers the most common ones.

23−This doesn't list any of the Ford runes, although there is now at least

22+This doesn't list any of the Ford runes, although there is now at least

24−some documentation for those [here](/docs/arvo/internals/ford/runes).

23+some documentation for those [here](/docs/arvo/internals/ford/runes).

26The following runes also exist, but are currently undocumented and not listed in the cheat sheet:

25The following runes also exist, but are currently undocumented and not listed in the cheat sheet:

docs/hoon/demo.md+33−33

@@ -30,59 +30,59 @@ $(count (add 1 count)) :: 15

31Hoon is a functional language. FizzBuzz is usually defined as a

32side effect, but officially Hoon has no side effects. Accordingly,

33−this code will *produce* a list of strings, not *print* a list of

33+this code will *produce* a list of strings, not *print* a list of

34−strings. (Of course, if you run this code from the Urbit

34+strings. (Of course, if you run this code from the Urbit

35−[_Dojo_](../../using/shell) (shell) you will be able to see the

35+[_Dojo_](../../using/shell) (shell) you will be able to see the

36product.)

38−The code produces a list in which each item is either a number

38+The code produces a list in which each item is either a number

39−(as a string), "Fizz", "Buzz", or "Fizzbuzz". The value `~` is

39+(as a string), "Fizz", "Buzz", or "Fizzbuzz". The value `~` is

40"null" and indicates the end of the list.

42−Line 1 uses the _[rune](../../about/glossary#rune)_ `|=` (pronounced

42+Line 1 uses the _[rune](../../about/glossary#rune)_ `|=` (pronounced

43−["bar-tis"](../syntax/#-glyphs-and-characters)) to define a function

43+["bar-tis"](../syntax/#-glyphs-and-characters)) to define a function

44−that takes one argument, labelled `end`. The argument must be of the

44+that takes one argument, labelled `end`. The argument must be of the

45type `@ud`, an unsigned decimal number.

47−Line 2 uses the rune `=/` (pronounced "tis-fas") to declare a variable,

47+Line 2 uses the rune `=/` (pronounced "tis-fas") to declare a variable,

48`count` of the unsigned decimal number type, with initial value `1`.

50Line 3 uses the rune `|-` ("bar-hep") to begin a loop.

52−Line 4 defines the product of the loop as a list of `tape`s.

52+Line 4 defines the product of the loop as a list of `tape`s.

53(A `tape` is a list of characters, one of Hoon's two string

54−types.) The rune `^-` ("ket-hep") is used for defining

54+types.) The rune `^-` ("ket-hep") is used for defining

55−the type of value the function must produce.

55+the type of value the function must produce.

57−Line 5 uses the rune `?:` ("wut-tis"), which is your classic "if, then,

57+Line 5 uses the rune `?:` ("wut-col"), which is your classic "if, then,

58−else" conditional. The "if" clause uses the irregular form of the rune

58+else" conditional. The "if" clause uses the irregular form of the rune

59−`.=` ("dot-tis"), one of the fundamental [Nock](../../nock/definition)

59+`.=` ("dot-tis"), one of the fundamental [Nock](../../nock/definition)

60−instructions, to perform an equality test on the values of `count` and

60+instructions, to perform an equality test on the values of `count` and

61−`end`. This will produce either `%.y` (yes, the number 0) or `%.n`

61+`end`. This will produce either `%.y` (yes, the number 0) or `%.n`

62−(no, 1) and consequently compute the "then" or "else" clause

62+(no, 1) and consequently compute the "then" or "else" clause

63−respectively.

63+respectively.

65−If the values of `count` and `end` are equal, line 6 (and the whole loop)

65+If the values of `count` and `end` are equal, line 6 (and the whole loop)

66returns the value `~`. The list is finished.

68If not, line 7 uses the rune `:-` ("col-hep") to produce a 'cell', which

69−is an ordered pair of Hoon values. This pair will be: (a) the next item

69+is an ordered pair of Hoon values. This pair will be: (a) the next item

70−in the list, determined by more `?:` conditionals in lines 8-14; and (b)

70+in the list, determined by more `?:` conditionals in lines 8-14; and (b)

71the rest of the list, determined by line 15.

73−(a) The head of the pair is: (i) "FizzBuzz", or "Fizz", or

73+(a) The head of the pair is: (i) "FizzBuzz", or "Fizz", or

74−"Buzz", if the respective tests hit; otherwise, it's

74+"Buzz", if the respective tests hit; otherwise, it's

75−(ii) the number in question, `count`. In case (ii), line 14

75+(ii) the number in question, `count`. In case (ii), line 14

76−uses the Hoon standard library function `++scow` to take the value of

76+uses the Hoon standard library function `++scow` to take the value of

77`count`, of type `@ud`, and pretty-print it as a `tape`.

79−(b) The tail of the pair—the rest of the output list—is

79+(b) The tail of the pair—the rest of the output list—is

80produced at line 15, which uses the irregular `$()` syntax for the rune

81−`%=` ("cen-tis") to repeat the loop set above (with the `|-` in line 3)

81+`%=` ("cen-tis") to repeat the loop set above (with the `|-` in line 3)

82−with `count` incremented.

82+with `count` incremented.

84−You can test this code by mounting your home desk with

84+You can test this code by mounting your home desk with

85−`|mount %` from the Dojo; saving the above code as

85+`|mount %` from the Dojo; saving the above code as

86−`home/gen/fizzbuzz.hoon` in your Urbit

86+`home/gen/fizzbuzz.hoon` in your Urbit

87−[pier](../../about/glossary#pier); then typing

87+[pier](../../about/glossary#pier); then typing

88`+fizzbuzz 100` in the dojo.

docs/hoon/library/4o.md+24−24

@@ -136,7 +136,7 @@ Used to build [tape]()s internally.

136Source

137------

138

139− ++ beer $|(@ [~ p=twig]) :: simple embed

139+ ++ beer $|(@ [~ p=hoon]) :: simple embed

140

141Examples

142--------

@@ -158,11 +158,11 @@ Source

158------

159

160 ++ beet $| @ :: advanced embed

161− $% [%a p=twig] :: take tape

161+ $% [%a p=hoon] :: take tape

162− [%b p=twig] :: take manx

162+ [%b p=hoon] :: take manx

163− [%c p=twig] :: take marl

163+ [%c p=hoon] :: take marl

164− [%d p=twig] :: take $+(marl marl)

164+ [%d p=hoon] :: take $+(marl marl)

165− [%e p=twig q=(list tuna)] :: element literal

165+ [%e p=hoon q=(list tuna)] :: element literal

166 == ::

167

168

@@ -226,8 +226,8 @@ Cases of arms by variance model.

226Source

227------

228

229− ++ foot $% [%ash p=twig] :: dry arm, geometric

229+ ++ foot $% [%ash p=hoon] :: dry arm, geometric

230− [%elm p=twig] :: wet arm, generic

230+ [%elm p=hoon] :: wet arm, generic

231 [%oak ~] :: XX not used

232 [%yew p=(map term foot)] :: XX not used

233 == ::

@@ -436,14 +436,14 @@ Source

436Examples

437--------

438

439−A `++wing` or `++twig`.

439+A `++wing` or `++hoon`.

440

441 > (ream '=+ a=4 ?-(a @ ~)')

442 [ %tsls

443 p=[%ktts p=p=%a q=[%dtzy p=%ud q=4]]

444 q

445 [ %wthz

446− p=[%.y p=~ q=~[%a]]

446+ p=[%.y p=~ q=~[%a]]

447 q=~[[p=[%axil p=[%atom p=~.]] q=[%bczp p=%null]]]

448 ]

449 ]

@@ -559,8 +559,8 @@ Source

559------

560

561 ++ tuna :: tagflow

562− [%d p=twig] :: dynamic list

562+ [%d p=hoon] :: dynamic list

563− [%e p=twig q=(list tuna)] :: element

563+ [%e p=hoon q=(list tuna)] :: element

564 [%f p=(list tuna)] :: subflow

565 == ::

566

@@ -568,7 +568,7 @@ Examples

568--------

569

570Leaf %a contains plain-text, %b an empty tag, %c a static list, %d a

571−dynamic list, %e a full node element containing a twig and a list of

571+dynamic list, %e a full node element containing a hoon and a list of

572tuna, and %f is a empty node.

573

574See also: [`++sail`]()

@@ -580,13 +580,13 @@ See also: [`++sail`]()

580

581List of expressions

582

583−List of [`++twig`]()s. In [`:*`](), for example, your contents is

583+List of [`++hoon`]()s. In [`:*`](), for example, your contents is

584a `++tusk`.

585

586Source

587------

588

589− ++ tusk (list twig) ::

589+ ++ tusk (list hoon) ::

590

591Examples

592--------

@@ -599,22 +599,22 @@ Examples

599

600

601***

602−### `++twig`

602+### `++hoon`

603

604Expression

605

606An expression, or AST.

607

608−See Twig section of Hoon reference

608+See Rune section of Hoon reference

609

610

611

612***

613### `++tyke`

614

615−List of 'maybe' twigs

615+List of 'maybe' hoons

616

617−List of [`++unit`]() [`++twig`](), or gaps left to be inferred, in [`++path`]()

617+List of [`++unit`]() [`++hoon`](), or gaps left to be inferred, in [`++path`]()

618parsing. When you use a path such as `/=main=/pub/src/doc` the path is in fact

619a `++tyke`, where the `=` are inferred from your current path.

620

@@ -622,7 +622,7 @@ a `++tyke`, where the `=` are inferred from your current path.

622Source

623------

624

625− ++ tyke (list (unit twig)) ::

625+ ++ tyke (list (unit hoon)) ::

626

627Examples

628--------

@@ -657,14 +657,14 @@ See also: `++seem`, `++vise`, `++type`

657***

658### `++tyre`

659

660−List, term to twig

660+List, term hoon

661

662−Associative list of [++term]() [`++twig`](), used in [jet]() hint processing.

662+Associative list of [`++term`]() [`++hoon`](), used in [jet]() hint processing.

663

664Source

665------

666

667− ++ tyre (list ,[p=term q=twig]) ::

667+ ++ tyre (list ,[p=term q=hoon]) ::

668

669

670

@@ -716,7 +716,7 @@ See also: [`++typo`](), [`++seer`]()

716Address in subject. A `++wing` is a path to a value in the subject. A

717term alone is the trivial case of a `++wing`.

718

719−See also: `++twig`

719+See also: `++hoon`

720

721 > (ream 'a.+.c')

722 [%cnzz p=~[%a [%.y p=3] %c]]

docs/hoon/rune/buc.md+1−1

@@ -22,7 +22,7 @@ x)))`, it's a normalizer and can be used as a mold.

22statically, so we can't actually tell if a mold matches this

23definition perfectly. This is not actually a problem.)

25−Twigs in the `$` family are macros designed for making molds.

25+Runes in the `$` family are macros designed for making molds.

26But any hoon may produce a mold. (This is why `model` is a

27synonym for `hoon`).

docs/hoon/rune/sig.md+1−1

@@ -7,7 +7,7 @@ title: Hint ~ ("sig")

8# Hint `~` ("sig")

10−Twigs that use Nock `10` to pass non-semantic info to the

10+Runes that use Nock `10` to pass non-semantic info to the

11interpreter.

13## Hoons

docs/hoon/rune/wut.md+4−4

@@ -6,7 +6,7 @@ title: Test ? ("wut")

6---

8# Test `?` ("wut")

9−

10Hoon has the usual branches and logical tests. For pattern

11matching, it also has a [`?=` ("wuttis")](./tis/) rune that tests whether a value

12matches the icon of a mold. And it has branch inference,

@@ -22,9 +22,9 @@ type for the branches of the `?:`. Branch inference also works

22for expressions which expand to `?:`.

24The test does not have to be a single `?=`; the compiler can

25−analyze arbitrary boolean logic ([`?&` ("wutpam")](./pam/),

25+analyze arbitrary boolean logic ([`?&` ("wutpam")](./pam/),

26−[`?|` ("wutbar")](./bar/), [`?!` ("wutzap")](./zap/)) with full

26+[`?|` ("wutbar")](./bar/), [`?!` ("wutzap")](./zap/)) with full

27−short-circuiting. Equality tests ([`.=` ("dottis")](../dot/tis/)) are *not*

27+short-circuiting. Equality tests ([`.=` ("dottis")](../dot/tis/)) are *not*

28analyzed.

30If the compiler detects that the branch is degenerate (only one

docs/hoon/syntax.md+62−62

@@ -7,8 +7,8 @@ title: Syntax

8# Hoon syntax

10−Hoon's syntax is unusual, and to beginners it can look a lot more

10+Hoon's syntax is unusual, and to beginners it can look a lot more

11−complex than it really is. However, we believe that anyone who

11+complex than it really is. However, we believe that anyone who

12learns Hoon syntax will find that it has a number of advantages.

14# Motivation

@@ -19,7 +19,7 @@ piles*, *indentation creep*, and *feature/label confusion*.

20## Terminator piles

22−*Terminator piles* are like Lisp's stacks of right parentheses.

22+*Terminator piles* are like Lisp's stacks of right parentheses.

23Significant whitespace solves this problem and creates others.

25Hoon has no terminator piles. Except for a 1-space / more-space

@@ -29,8 +29,8 @@ distinction, it has no significant whitespace.

30*Indentation creep* is a problem caused by indentation conventions

31where the indentation point is a function of expression tree

32−depth. This problem is especially irritating when working with

32+depth. This problem is especially irritating when working with

33−long functions. It's true that short functions are better, but

33+long functions. It's true that short functions are better, but

34long ones sometimes need to be written.

36A procedural block has a backbone of statements which flows

@@ -48,19 +48,19 @@ shaped more or less like procedural programs.

48## Feature/label confusion

50*Feature/label confusion* (FLC) is the result of any syntax that

51−makes it hard for the eye to tell whether a token on the screen is

51+makes it hard for the eye to tell whether a token on the screen is

52−a feature of the language, or a label in the program. For example,

52+a feature of the language, or a label in the program. For example,

53in Lisp a special form has the same syntax as a function call.

55The worst-case result of FLC is "DSL cancer." Every source file

56is effectively written in its own domain-specific language. To

57read a new file is to learn a new language—"write-only code."

59−User-level macros, operator overloading, even excessive use of

59+User-level macros, operator overloading, even excessive use of

60−higher-order programming, can all lead quickly to the tragedy of

60+higher-order programming, can all lead quickly to the tragedy of

61write-only code.

63−Hoon has no FLC, user-level macros, or overloading. It does

63+Hoon has no FLC, user-level macros, or overloading. It does

64support higher-order programming; write-only Hoon can certainly be

65(and has been) written. But good Hoon style is to avoid it.

@@ -71,12 +71,12 @@ regularities. We'll cover those here.

72## Glyphs and characters

74−Hoon source uses ASCII text. Hoon does not accept non-ASCII

74+Hoon source uses ASCII text. Hoon does not accept non-ASCII

75text in source files, except UTF-8 in quoted strings. Hard

76tab characters are illegal.

78−Hoon is a heavy punctuation user. Reading off code aloud

78+Hoon is a heavy punctuation user. Reading off code aloud

79−using the proper names of ASCII symbols is tedious, so we've

79+using the proper names of ASCII symbols is tedious, so we've

80mapped each punctuation glyph to a syllable:

82```

@@ -94,31 +94,31 @@ fas / pat @ wut ?

94zap !

95```

97−You don't need to memorize these glyph names, but it might help.

97+You don't need to memorize these glyph names, but it might help.

98Code is often vocalized or subvocalized. "pal" is easier to say,

99aloud or silently, than "left paren".

100

101Note that the list includes two separate whitespace forms: `ace`

102for a single space; `gap` is either 2+ spaces or a newline. In Hoon,

103the only significance in whitespace is the difference between

104−`ace` and `gap`. Comments also count as `gap` whitespace—they

104+`ace` and `gap`. Comments also count as `gap` whitespace—they

105start with `::` and run to the end of the line.

106

107−An 80-column right margin is strongly encouraged. Really

107+An 80-column right margin is strongly encouraged. Really

108−well-groomed Hoon uses a 55-column code margin and puts a standard

108+well-groomed Hoon uses a 55-column code margin and puts a standard

109line comment at column 57.

110

111## Expressions and Runes

112

113−Each regular Hoon expression begins with a

113+Each regular Hoon expression begins with a

114−[rune](../about/glossary/#-rune). A rune is a pair

114+[rune](../about/glossary/#-rune). A rune is a pair

115−of ASCII punctuation marks (a digraph)—e.g., `:-`. The first

115+of ASCII punctuation marks (a digraph)—e.g., `:-`. The first

116−glyph in the rune indicates the category—e.g., `:` runes make

116+glyph in the rune indicates the category—e.g., `:` runes make

117−[cells](../about/glossary/#-cell) (i.e., ordered

117+[cells](../about/glossary/#-cell) (i.e., ordered

118−pairs). We pronounce runes using their glyph names—for `:-`,

118+pairs). We pronounce runes using their glyph names—for `:-`,

119we say "colhep".

120

121−Each rune is followed by one or more subexpressions. The number and

121+Each rune is followed by one or more subexpressions. The number and

122kind of subexpressions depend on the rune used.

123

124```

@@ -126,25 +126,25 @@ kind of subexpressions depend on the rune used.

1263

127```

128

129−This Hoon uses `:-` to produce a cell: `[25 3]`. There are always two

129+This Hoon uses `:-` to produce a cell: `[25 3]`. There are always two

130−subexpressions following the `:-` in syntactically correct Hoon code,

130+subexpressions following the `:-` in syntactically correct Hoon code,

131−the first of which, when evaluated, becomes the *head* (i.e., the left)

131+the first of which, when evaluated, becomes the *head* (i.e., the left)

132and the second of which becomes the *tail* (i.e., the right).

133

134−Hoon expressions are just called

134+Hoon expressions are just called

135[hoons](../about/glossary/#-a-hoon), because a rune's subexpression can itself

136−be a Hoon expression (i.e. another rune). You'll start to see this tree-like,

136+be a Hoon expression (i.e. another rune). You'll start to see this tree-like,

137−recursive structure the more you program in Hoon. You can think of one Hoon

137+recursive structure the more you program in Hoon. You can think of one Hoon

138−file being composed of multiple hoons. The subexpressions following the

138+file being composed of multiple hoons. The subexpressions following the

139rune are sometimes called the *children* of that hoon.

140

141## Tall and flat forms

142

143There are two kinds of Hoon expression syntax: *tall* and *flat*.

144−Most runes can be used in both tall and flat hoons. Tall hoons can

144+Most runes can be used in both tall and flat hoons. Tall hoons can

145contain flat hoons, but not vice versa.

146

147−The `:-` expression in the last subsection was in tall form. Here's

147+The `:-` expression in the last subsection was in tall form. Here's

148the flat equivalent:

149

150`:-(25 3)`

@@ -167,8 +167,8 @@ principles at all. All irregular forms are flat.

16723

168```

169

170−The `.=` rune tests for equality the two subexpressions that

170+The `.=` rune tests for equality the two subexpressions that

171−follow, and returns a boolean. Above is the tall, regular form of

171+follow, and returns a boolean. Above is the tall, regular form of

172`.=`. Below is the irregular form:

173

174`=(22 23)`

@@ -178,29 +178,29 @@ Some hoons have *only* irregular forms.

178## Tall regular form

179

180Tall regular forms start with a rune followed by a `gap`.

181−(Remember, a `gap` is any whitespace other than `ace`.) After

181+(Remember, a `gap` is any whitespace other than `ace`.) After

182−that are the number and types of subexpressions appropriate for

182+that are the number and types of subexpressions appropriate for

183−that rune. Each subexpression is separated from its neighboring

183+that rune. Each subexpression is separated from its neighboring

184subexpressions by a `gap`.

185

186−Let's call everything in the hoon after the initial rune the hoon

186+Let's call everything in the hoon after the initial rune the hoon

187−*body*. There are four body subtypes: *fixed*, *running*, *jogging*,

187+*body*. There are four body subtypes: *fixed*, *running*, *jogging*,

188−and *[battery](../about/glossary/#-battery)*.

188+and *[battery](../about/glossary/#-battery)*.

189

190−Runes with a *fixed* number of subexpressions self-terminate. For

190+Runes with a *fixed* number of subexpressions self-terminate. For

191−instance, the `:-` and `.=` runes each have two subexpressions

191+instance, the `:-` and `.=` runes each have two subexpressions

192and are self-terminating. Otherwise the hoon is terminated by both

193a `gap`, then either `==` (*running* or *jogging*, most hoons) or

194`--` (*battery*).

195

196−The *running* body has a list of *children* (i.e., subexpressions).

196+The *running* body has a list of *children* (i.e., subexpressions).

197−The *jogging* body has a list of child pairs, where the members of

197+The *jogging* body has a list of child pairs, where the members of

198each pair are separated by a `gap`. The *battery* body is

199a list of symbol-child pairs, separated by a gap, prefixed by `++`

200and then a gap.

201

202−This definition is enough to write Hoon that will parse. But

202+This definition is enough to write Hoon that will parse. But

203−writing code with optimal whitespace management requires some

203+writing code with optimal whitespace management requires some

204additional informal conventions.

205

206Whitespace design in Hoon is an art, not a science. It involves

@@ -210,13 +210,13 @@ But it would at least take machine learning, not a rule engine.)

210

211There are only two real *rules* in Hoon whitespace design: don't

212go past 80 characters, and don't use (completely) blank lines.

213−Otherwise, if it looks good and is easy to read, it's good. The

213+Otherwise, if it looks good and is easy to read, it's good. The

214best way to learn the art is to do everything by convention

215until you know what you're doing. Here are the conventions:

216

217### Conventions: *fixed*

218

219−Twig bodies with *fixed* fanout use "backstep" indentation, which

219+Rune bodies with *fixed* fanout use "backstep" indentation, which

220slopes backward and to the right by two spaces per line. The first

221hoon child is two spaces after the end of the rune.

222

@@ -239,13 +239,13 @@ r

239s

240```

241

242−In optimal usage of backstep indentation, the most complicated hoons

242+In optimal usage of backstep indentation, the most complicated hoons

243are at the bottom, keeping code flow vertical rather than diagonal.

244

245### Conventions: *running*

246

247A *running* hoon body (a simple child list) puts the first child two

248−spaces after the end of the rune, and the following children straight

248+spaces after the end of the rune, and the following children straight

249down:

250

251A *running* example:

@@ -261,10 +261,10 @@ A *running* example:

261

262### Conventions: *jogging*

263

264−A *jogging* hoon body (a list of child pairs) is like a running

264+A *jogging* hoon body (a list of child pairs) is like a running

265−body, but with a pair of children on each line, separated by

265+body, but with a pair of children on each line, separated by

266−two spaces. Most jogging bodies start with a *fixed* sequence;

266+two spaces. Most jogging bodies start with a *fixed* sequence;

267−the first jogging pair is below and two steps backward from the

267+the first jogging pair is below and two steps backward from the

268last fixed child.

269

270There are two jogging conventions: *flat* (pair on one line) and

@@ -297,8 +297,8 @@ A *tall jogging* example (preceded by *1-fixed* `p`):

297

298A *battery* body has a list of symbol-child pairs, for the

299[battery](../about/glossary/#-battery)

300−of a

300+of a

301−[core](../about/glossary/#-core). A

301+[core](../about/glossary/#-core). A

302conventional example:

303

304```

@@ -314,7 +314,7 @@ conventional example:

314

315## Flat regular form

316

317−Flat regular form starts with the rune, followed by `pal`, `(`

317+Flat regular form starts with the rune, followed by `pal`, `(`

318(left parenthesis), followed by a body whose subexpressions

319are separated by `ace` (one space), followed by `par`, `)` (right

320parenthesis).

@@ -356,10 +356,10 @@ appropriate.

356

357In the *ultralapidary* naming style, labels are single letters,

358starting in order of construction from `a`, or within a tuple

359−[mold](../about/glossary/#-mold) `p`. Hoon

359+[mold](../about/glossary/#-mold) `p`. Hoon

360−uses single-letter names for the same reason Algol style

360+uses single-letter names for the same reason Algol style

361−languages pass arguments by order, rather than keyword. Naming

361+languages pass arguments by order, rather than keyword. Naming

362−items by order makes sense when there are no more than three or

362+items by order makes sense when there are no more than three or

363four; five is stretching it; six is outright ridiculous.

364

365For example, when defining `add`, we want to name the operands

docs/nock/implementations.md−1

@@ -2,7 +2,6 @@

2navhome: /docs/

3title: Implementation

4sort: 6

5−next: true

6---

5---

8# C implementation

7# C implementation