039466b · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

Merge branch 'master-joshuareagan'

039466bKeaton Dunsford9 years ago

docs/about/glossary.md+192−104

compare with master

unifiedsplit

@@ -1,11 +1,10 @@

1---

2−navhome: '/docs'

2+navhome: /docs/

3−next: True

4sort: 3

3sort: 3

5−title: Urbit glossary

4+title: Glossary

6---

5---

8−# Urbit Glossary

7+# Glossary

10Urbit is renowned for its exotic terminology. Here's a simple overview

9Urbit is renowned for its exotic terminology. Here's a simple overview

11from the strange words in.

10from the strange words in.

@@ -29,12 +28,13 @@ classed by the number of bits in their address:

30Any ship can be called an "urbit."

29Any ship can be called an "urbit."

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

32−> A summary [here](http://urbit.org/posts/address-space/).

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

33−

33+

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

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

36−just a 32-bit number, like an IP address, that we turn into a

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

37−human-memorable string.

37+that we turn into a human-memorable string.

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

40control with a cryptographic key, like a Bitcoin wallet. As in Bitcoin,

@@ -57,7 +57,7 @@ whose number is its bottom half. So the planet `~firbyr-napbes`,

57`48.879`, whose parent is `~mun`, `0xef`, `239`. The parent of `~mun`

58and all galaxies is `~zod`, `0`.

60−##### <h5 id="pier">Pier</h5>

60+#### pier

62A ship's *pier* is its Unix directory. For planets the name of the pier is usually the planet name.

@@ -65,60 +65,62 @@ A ship's *pier* is its Unix directory. For planets the name of the pier is usua

66> Nock is a Turing-complete, non-lambda combinator interpreter.

68+- <h6 id="-nock-noun">noun:</h6> an _atom_ or a _cell_

68−- *atom*: any natural number

69+- <h6 id="-nock-atom">atom:</h6> any natural number

69−- *cell*: any ordered pair of nouns

70+- <h6 id="-nock-cell">cell:</h6> any ordered pair of nouns

70−- *formula*: a noun - a function at the Nock level

71−- *noun*: an *atom* or a *cell*

72−- *product*: a noun - the result of evaluating a formula against a

73− subject

74−- *subject*: a noun - the data against which a `formula` is

71+- <h6 id="-nock-subject">subject:</h6> a noun - the data against which a _formula_ is

75 evaluated

72 evaluated

73+- <h6 id="-nock-formula">formula:</h6> a noun - a function at the Nock level

74+- <h6 id="-nock-product">product:</h6> a noun - the result of evaluating a formula against a

75+ subject

77*See [Nock definition](../../nock/definition/).*

79−### Hoon

79+## Hoon

81> Hoon is a strict, higher-order typed functional language that compiles

82> itself to Nock.

84+#### arm

85+

84−###### <h6 id="arm">arm:</h6> a named, functionally-computed attribute of a core

86+An _arm_ is a named, functionally-computed attribute of a [core](#-core).

86−The *twig* of each arm is compiled to a Nock formula, with the

88+The [hoon](#-a-hoon) of each arm is compiled to a Nock formula, with the

87enclosing `core` itself as the subject.

89enclosing `core` itself as the subject.

89There are two kinds of arms: *dry* and *wet*. Most arms are dry.

91There are two kinds of arms: *dry* and *wet*. Most arms are dry.

91−- *dry*: normal, `++`, polymorphic by means of *variance*

93+- <h6 id="-arm-dry">dry:</h6> normal, `++`, polymorphic by means of *variance*

93For a dry arm, we ask, is the new payload compatible with the old

95For a dry arm, we ask, is the new payload compatible with the old

94payload (against which the core was compiled)?

96payload (against which the core was compiled)?

96−- *wet*: unusual, `+-`, polymorphic by means of *genericity*

98+- <h6 id="-arm-wet">wet:</h6> unusual, `+-`, polymorphic by means of *genericity*

98−A wet arm uses the twig as a macro. We create a new type analysis

100+A wet arm uses the hoon as a macro. We create a new type analysis

99path, which works as if we expanded the callee with the caller's

101path, which works as if we expanded the callee with the caller's

100context.

102context.

101

103

102−*See [advanced types](/hoon/advanced)*.

104+*See [advanced types](../../hoon/advanced/)*.

103

105

104−###### atom

106+#### atom

105

107

106−A Hoon *atom* span describes a Nock atom, with two additional pieces

108+A Hoon _atom_ type describes a Nock atom, with two additional pieces

107of metadata: an *aura*, and an optional constant.

109of metadata: an *aura*, and an optional constant.

108

110

109−An atom span is *warm* or *cold* based on whether the constant exists.

111+An atom type is *warm* or *cold* based on whether the constant exists.

110

112

111−- *warm*: if the constant is `~` (null), any atom is in the span

113+- <h6 id="-atom-warm">warm:</h6> if the constant is `~` (null), any atom is in the type

112−- *cold*: if the constant is `[~ atom]`, its only legal value is

114+- <h6 id="-atom-cold">cold:</h6> if the constant is `[~ atom]`, its only legal value is

113 `atom`.

115 `atom`.

114

116

115*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*

117*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*

116

118

117−###### aura: a soft atom type

119+#### aura

118

120

119−*aura* is a name for an atom type. It represents the structure of an

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

120−atom in a string beginning with `@`. An aura may represent units,

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

121−print format, or other semantics. Its constraints on the value of an

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

122atom aren't enforced in any way.

124atom aren't enforced in any way.

123

125

124Two auras are compatible if one is a prefix of the other. You can

126Two auras are compatible if one is a prefix of the other. You can

@@ -128,76 +130,133 @@ auras.

128

130

129Some common auras and their aliases:

131Some common auras and their aliases:

130

132

131−- *term* (`@tas`): a symbol - an atomic ASCII string which obeys

133+- <h6 id="-aura-term">term:</h6> (`@tas`): a symbol - an atomic ASCII string which obeys

132 symbol rules: lowercase and digit only, infix hyphen ("kebab-case"),

134 symbol rules: lowercase and digit only, infix hyphen ("kebab-case"),

133 first character must be lowercase alphabetic.

135 first character must be lowercase alphabetic.

134−- *cord* (`@t`): UTF-8 text, least-significant-byte first

136+- <h6 id="-aura-cord">cord:</h6> (`@t`): UTF-8 text, least-significant-byte first

135−- *char* (`@tD`): a character, a single unicode byte (for multi-byte

137+- <h6 id="-aura-char">char:</h6> (`@tD`): a character, a single unicode byte (for multi-byte

136 characters and codepoints, see `@c`)

138 characters and codepoints, see `@c`)

137

139

140+You can find the list of all auras [here](../../hoon/twig/atom/sand/).

141+

138*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*.

142*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*.

139

143

140−###### <h6 id="core">core:</h6> a code-data cell

144+#### core

141

145

142−The code (*battery*) is the head, the data (*payload*) is the tail. All

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

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

143−code-data structures in normal languages (functions, objects, modules,

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

144−etc) become *core*s in Hoon.

149+become _core_s in Hoon.

145

150

146−- <h6 id="battery">*battery*:</h6> the code of a core, a tree of *arms*

151+- <h6 id="-core-battery">battery:</h6> the code of a core, a tree of *arms*

147−- <h6 id="payload">*payload*:</h6> the data in a core

152+- <h6 id="-core-payload">payload:</h6> the data in a core

148

153

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

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

150

155

156+#### face

157+

151−###### face: a labeled subtree

158+A Hoon _face_ is a labeled subtree.

152

159

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

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

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

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

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

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

156

163

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

157−A *face* is a span that wraps a name (`@tas`) around another span.

165+`@tas`) around another type.

158

166

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

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

160

168

161−###### <h6 id="gate">gate:</h6> a function/lambda/closure

169+#### gate

162

170

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

163−A *gate* is a core with one arm. To call a gate on an argument,

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

164−replace the sample (at [tree

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

165−address](../../hoon/twig/limb/limb/) `+6` in the core) with the

166−argument, and then compute the arm.

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

167

175

168−The payload of a gate has a shape of `{sample context}`.

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

169

177

170−- *sample*: the argument tuple

178+- <h6 id="-gate-sample">sample:</h6> the argument tuple

171−- *context*: the subject in which the gate was defined

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

172

180

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

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

174−[`%-` or `:call`](../../hoon/twig/cen-call/hep-call/) (the `twig` for

182+[`%-` ("cenhep")](../../hoon/twig/cen-call/hep-call/) (the

175−calling a `gate`).*

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

184+

185+#### <h4 id="-a-hoon">hoon</h4>

186+

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

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

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

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

191+into an AST is a single `hoon`.

192+

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

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

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

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

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

198+

199+```

200+[%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]]

201+```

202+

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

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

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

206+decimal).

176

207

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

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

210+

211+```

212+(ream ':+(12 7 %a)')

213+```

214+

215+The result should be:

216+

217+```

218+[%clls p=[%sand p=%ud q=12] q=[%sand p=%ud q=7] r=[%rock p=%tas q=97]]

219+```

220+

221+#### limb

222+

177−###### limb: attribute or variable reference

223+A _limb_ is an attribute or variable reference.

178

224

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

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

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

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

181"foo". If a face is found, the result is a leg, if a core is

227"foo". If a face is found, the result is a leg, if a core is

182found, the result is the product of the arm.

228found, the result is the product of the arm.

183

229

184−- *leg*: a subexpression, or subtree of the subject.

230+- <h6 id="-limb-leg">leg:</h6> a subexpression, or subtree of the subject.

185−- *wing*: a list of limbs, searched from right to left (`a.b` means

231+- <h6 id="-limb-wing">wing:</h6> a list of limbs, searched from right to left (`a.b` means

186 `b` within `a`).

232 `b` within `a`).

187

233

188−*See [Limbs and wings](../../hoon/twig/limb)*

234+*See [Limbs and wings](../../hoon/twig/limb/)*

189

235

190−###### loobean: a Hoon boolean

236+#### loobean

191

237

192−`0` (`%.y`) is *yes*, `1` (`%.n`) is *no*.

238+A _loobean_ is a Hoon boolean. `0` (`%.y`) is *yes*, `1` (`%.n`) is *no*.

193

239

194> Why? It's fresh, it's different, it's new. And it's annoying. And it

240> Why? It's fresh, it's different, it's new. And it's annoying. And it

195> keeps you on your toes. And it's also just intuitively right.

241> keeps you on your toes. And it's also just intuitively right.

196

242

197−###### metal: a variance model

243+#### mark

244+

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

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

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

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

249+marks, etc.

198

250

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

252+for different urbits to make sure they mean the same thing by the

253+same mark. However, when incompatibility happens, marks ensure

254+that we at least handle the situation in a predictable way.

255+

256+#### metal

257+

199−Every core has a *metal* which defines its variance model (ie, the

258+Every core has a _metal_ which defines its variance model (ie, the

200−properties of the span of a compatible core). The default is `gold`

259+properties of the type of a compatible core). The default is `gold`

201(invariant).

260(invariant).

202

261

203- `gold`: *invariant*

262- `gold`: *invariant*

@@ -207,69 +266,98 @@ properties of the span of a compatible core). The default is `gold`

207

266

208*See [advanced types](/hoon/advanced)*.

267*See [advanced types](/hoon/advanced)*.

209

268

210−###### <h6 id="mold">mold:</h6> a type constructor / validator

269+#### mold

270+

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

272+and producing a range with a type, a set of nouns.

211

273

212−A *mold* is an idempotent gate (function), accepting any noun, and

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

213−producing a range with a useful span.

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

276+validate untrusted network data.

214

277

278+Here's some common mold terminology:

279+

215−- *bunt*: the value a mold produces when normalizing its default

280+- <h6 id="-mold-bunt">bunt:</h6> the value a mold produces when normalizing its default

216 sample

281 sample

217−- *icon*: the span of the mold's range

282+- <h6 id="-mold-icon">icon:</h6> the type of the mold's range

218

283

219−*See [mold twigs](/hoon/twig/buc-mold/).*

284+*See [mold hoons](../../hoon/twig/buc-mold/).*

220

285

221−###### nest: type compatibility test

286+#### nest

222

287

223−*nest* is an internal function on two spans, which produces yes if the

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

289+compatibility test. `nest` produces yes if the

224−set of nouns in the second span is provably a subset of the first.

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

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

292+error. This is one of the most commons errors in Hoon programming.

225

293

226*See [advanced types](../../hoon/advanced/)*.

294*See [advanced types](../../hoon/advanced/)*.

295+*See [troubleshooting](../../hoon/troubleshooting/#-nest-fail)*.

227

296

228−###### slot: a tree addressing scheme

297+#### rune

229

298

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

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

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

300+[Hoon expression](#-a-hoon).

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

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

234

301

235−###### <h6 id="span">span:</h6> an inferred type

302+For example, the rune [`?:`](../../hoon/twig/wut-test/col-if/) is

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

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

305+[`?` family](../../hoon/twig/wut-test/) are all conditionals.

236

306

237−A *span* defines a set (finite or infinite) of nouns and ascribes some

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

238−semantics to it. There is no Hoon syntax for a span; it is always

308+by its respective children—into an AST node is simply called

239−produced as the inferred range of an expression (*twig*).

309+a [`hoon`](#-a-hoon).

240

310

241−*See [basic types](../../hoon/basic/#-type-span-and-mold).*

311+Runes have two syntactic forms, _tall_ and _flat_:

242

312

243−###### <h6 id="twig">twig:</h6> a Hoon expression

313+- <h6 id="-rune-tall">tall:</h6> multiple lines, no parentheses, two or more spaces between

314+ tokens

244

315

245−A *twig* is a Hoon expression. Specifically, twig is the mold for the

316+ Example:

246−noun that a Hoon source expression compiles to. A twig is always a cell.

247

317

248−A twig has one of two forms: `{twig twig}`, which produces the ordered

318+ ```

249−pair of the two twigs, or a cell `{stem bulb}`, where `stem` is an

319+ ~zod:dojo> %+ add 2 2

250−atomic symbol.

320+ 4

321+ ```

322+- <h6 id="-rune-flat">flat:</h6> one line, parentheses, one space between tokens

251

323

252−- <h6 id="stem">*stem*:</h6> an atomic symbol (`@tas`) - the name of a twig.

324+ Example:

253−- <h6 id="bulb">*bulb*:</h6> The mold of the twig's contents.

254

325

255−Most twigs have a *regular form*, beginning with a *rune*. Some twigs

326+ ```

256−also have a syntactic *irregular form*; a few have *only* an *irregular form*.

327+ ~zod:dojo> %+(add 2 2) :: regular flat form

328+ 4

257

329

258−- <h6 id="rune">*rune*:</h6> a pair of ASCII symbols used to begin a twig.

330+ ~zod:dojo> (add 2 2) :: irregular flat form

331+ 4

332+ ```

259

333

260−For example, the rune [`?:`](../../hoon/twig/wut-test/col-if/) is

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

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

335+forms are flat.

262−in a rune represents a family of related `twig`s. For example, the

263−[`?` family](../../hoon/twig/wut-test/) are all conditionals.

264

336

265−A regular twig has two syntactic forms, *tall* and *flat*:

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

338+[expressions](../../hoon/twig/), and [syntax](../../hoon/syntax/)*.

266

339

267−- *tall*: multiple lines, no parentheses, two or more spaces between

268− tokens

269−- *flat*: one line, parentheses, one space between tokens

270

340

271−Tall twigs can contain flat ones, but not vice versa. All irregular

341+#### slot

272−forms are flat.

342+

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

344+

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

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

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

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

349+

350+#### type

351+

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

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

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

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

356+

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

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

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

360+of the simpler built-in types.

361+

362+*See [basic types](../../hoon/basic/#-type-span-and-mold).*

273

363

274−*See [twig concept](../../hoon/concepts/#-twig-expression),

275−[expressions](../../hoon/twig/), and [syntax](../../hoon/syntax/)*.

docs/hoon/concepts.md+128−104

@@ -10,25 +10,19 @@ title: Concepts

10Usually, a new language is an improvement on one you already

11know. If it isn't, it probably at least shares concepts with a

12large family of relatives. These concepts come with words, like

13−*type* or *function*, that map cleanly onto its semantics.

13+_variable_ or _function_, that map cleanly onto its semantics.

15−In Hoon we throw away almost all these words and invent new

15+In Hoon we throw away many of these words and invent new

16ones, which mean almost the same things. But why?

18## Motivation

20Hoon has no close relatives. The normal jargon of programming

21−maps poorly onto its semantics. For example, although Hoon is a

21+maps poorly onto its semantics. Some of the common concepts used

22−typed language, the term "type" is not formally defined in Hoon.

23−"Type" is a great word, but Hoon has three separate concepts

24−which could comfortably claim it. We say "type" all the time; we

25−mean [`span`](#span), or `mold`, or `mark`, or possibly all three.

26−

27−Other common programming concepts used only informally in Hoon

28−are "function," "object," "event," "expression," "variable,"

22+only informally in Hoon include "function," "object," "event,"

29−"label," "closure", "environment," "scope," and probably a few

23+"variable," "label," "closure", "environment," "scope," and probably

30−more. We do use these words informally, but we're always making

24+a few more. We do use these words informally, but we're always

31−an analogy whose precision depends on context.

25+making an analogy whose precision depends on context.

33Hoon has concepts *like* all these abstractions, but they remain

27Hoon has concepts *like* all these abstractions, but they remain

34*false cognates*. The closer an inexact cognate, the more

28*false cognates*. The closer an inexact cognate, the more

@@ -38,11 +32,11 @@ a few new words is a small price for avoiding this pain point.

38## Concepts

32## Concepts

40A few major Hoon concepts: `noun` (data), `nock` (interpreter),

34A few major Hoon concepts: `noun` (data), `nock` (interpreter),

41−[`mint`](#mint) (compiler), [`span`](#span) (type), [`twig`](#twig) (expression),

35+[`hoon`](#-hoon) (AST node), [`mint`](#-mint) (compiler), [`type`](#-type) (type),

42`gate` (function), `mold` (constructor), `core` (object), `mark`

36`gate` (function), `mold` (constructor), `core` (object), `mark`

43(protocol).

37(protocol).

45−### `noun` (data value)

39+### <a name="-noun">`noun`</a> (data value)

47A value in Hoon is called a `noun`. A noun is either a

41A value in Hoon is called a `noun`. A noun is either a

48unsigned integer of any size (`atom`), or an ordered pair of any

42unsigned integer of any size (`atom`), or an ordered pair of any

@@ -51,27 +45,29 @@ simpler (Lisp atoms effectively have dynamic type bits).

52The simplest noun syntax uses brackets, like `[a b]` for the cell

46The simplest noun syntax uses brackets, like `[a b]` for the cell

53of `a` and `b`. Brackets nest right; `[a b c d]` is `[a [b [c

47of `a` and `b`. Brackets nest right; `[a b c d]` is `[a [b [c

54−d]]]`. You'll also see braces: `{a b c d}`.

48+d]]]`.

56−A noun list, by convention, points right and is zero-terminated.

50+A noun list, by convention, goes from left to right and is

57−Hoon uses tuples (improper nouns) more freely than Lisp; only

51+null-terminated. That said, Hoon uses tuples (improper nouns) more

58−genuinely iterative structures are null-terminated lists.

52+freely than Lisp; only genuinely iterative structures are

53+null-terminated lists.

60−When an atom is used as a string (a `cord`), the bytes are always

55+When an atom is used as a string (a `cord`), the bytes are always UTF-8

61−UTF-8 in LSB first order. When you see `foo`, `$foo`, `%foo`,

56+in LSB first order. When you see `'foo'` and `%foo`, this refers to the

62−etc, this refers to the integer `0x6f.6f66`, aka `7.303.014`.

57+integer `0x6f.6f66`, aka `7.303.014`. (Hoon syntax uses `.` to break

63−(Hoon syntax breaks integer atoms in the German style.)

58+integer atoms in the German style, because `.`'s are URL-safe and `,`'s

59+aren't.)

65One common operation on nouns is `slot`, a tree addressing

61One common operation on nouns is `slot`, a tree addressing

66scheme which maps an atom to a subtree. The whole noun is slot

62scheme which maps an atom to a subtree. The whole noun is slot

67`1`; the left child of `n` is `2n`, the right child `2n+1`.

63`1`; the left child of `n` is `2n`, the right child `2n+1`.

69−Nothing in Nock, Hoon or Urbit can create cycles in a noun or

65+Nothing in Nock, Hoon, or Urbit can create cycles in a noun or

70detect pointer equivalence. Nouns are generally implemented

66detect pointer equivalence. Nouns are generally implemented

71with reference counting, and have a lazy short Merkle hash to

67with reference counting, and have a lazy short Merkle hash to

72help with equality testing and associative containers.

68help with equality testing and associative containers.

74−### `nock` (interpreter)

70+### <a name="-nock">`nock`</a> (interpreter)

76Hoon compiles itself to the [Nock](../../nock) VM. Nock is a

72Hoon compiles itself to the [Nock](../../nock) VM. Nock is a

77Turing-complete, non-lambda combinator function. The function

73Turing-complete, non-lambda combinator function. The function

@@ -82,17 +78,54 @@ it's still fun and useful to [learn more](../../nock).

83## Compilation concepts

79## Compilation concepts

85−### <a name="mint">`mint`</a> (compiler)

81+### <a name="-hoon">`hoon`</a> (AST node)

87−[`mint`](#mint) is the Hoon compiler. It maps a cell `{span twig}` to a

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

88−cell `{span nock}`, where a [`span`](#span) is a type, a [`twig`](#twig)

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

89−is a compiled expression (AST), and a `nock` is a Nock formula. `mint` accepts

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

90−a subject type and a source expression; it produces a product type

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

91−and an executable formula.

87+into an AST is a single `hoon`.

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

90+is a constant such as `%brts` (from the source `|=`, i.e. "bartis"),

91+and is matched up with the appropriate type of data (often more

92+`hoon`s, from source subexpressions). For example, the expression

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

94+

95+```

96+[%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]]

97+```

98+

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

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

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

102+decimal).

103+

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

105+containing Hoon source. Try the following in `dojo`:

106+

107+```

108+(ream ':+(12 7 %a)')

109+```

110+

111+The result should be:

112+

113+```

114+[%clls p=[%sand p=%ud q=12] q=[%sand p=%ud q=7] r=[%rock p=%tas q=97]]

115+```

116+

117+### <a name="-mint">`mint`</a> (compiler)

118+

119+[`mint`](#-mint) is the Hoon compiler. It maps a cell `[type hoon]`

120+to a cell `[type nock]`, where a [`type`](#-type) is type

121+information, a [`hoon`](#-hoon) is a parsed expression (AST), and a

122+`nock` is a Nock formula. `mint` takes as input the subject type

123+and a parsed source expression; it produces a product type and an

124+executable formula.

125+

93−Calculating the output type from the input type and the source

126+Calculating the output type from the input `hoon` and subject type

94−code is called "type inference." If you've used another typed

127+is called "type inference". If you've used another typed functional

95−functional language, like Haskell, Hoon's type inference does the

128+language, like Haskell, the Hoon compiler's type inference does the

96same job but with less intelligence.

129same job but with less intelligence.

130

98Haskell infers backward and forward; Hoon only infers forward.

131Haskell infers backward and forward; Hoon only infers forward.

@@ -105,55 +138,39 @@ which makes your program more readable anyway. Also, the dumber

105the compiler, the easier it is for a dumb human to understand

138the compiler, the easier it is for a dumb human to understand

106what the compiler is thinking.

139what the compiler is thinking.

107

140

108−### <a name="twig">`twig`</a> (expression)

141+The `mint` gate is inside the core `++ ut`, so call it using the

109−

142+following syntax:

110−A [`twig`](../reference) is a Hoon AST node, the result of parsing a

111−source expression. A Hoon source file encodes one twig.

112

143

113−As the noun that the parser produces, a twig is a tagged union of

144+```

114−the form `{stem bulb}`, where `stem` (the tag) is a `cord` which

145+(~(<gate> <core> <arg 1>) <arg 2> <arg 3>)

115−controls the type of `bulb` (the data).

146+```

116−

117−As text, each twig has both regular and irregular syntax forms.

118−Regular syntax can be either *tall* or *flat*: multiline or

119−single-line. Irregular syntax is always flat. Tall twigs can

120−contain flat twigs, but not vice versa.

121−

122−Regular forms always start with a *sigil*, which is either a

123−*keyword* or a *rune* at the programmer's choice. A keyword is

124−the stem cord.

125

147

126−For most stems, tall regular form has no delimiter or terminator,

148+The `<gate>` is mint, the `<core>` is `ut`, `<arg 1>` is the subject

127−eliminating the `)))))` problem common in functional languages.

149+type, and `<arg 3>` is the parsed Hoon AST (i.e., a `hoon` from the

128−Hoon also uses an unusual "backstep" indentation pattern to

150+last section). What's `<arg 2>`? It's another piece of type

129−control left-margin drift.

151+information. As part of the type-checking process, mint checks that

152+the output type "nests" within the input type, i.e. that the output

153+type is a subset of the input type. If not, mint halts with a

154+`nest-fail` crash.

130

155

131−Hoon is mildly whitespace-sensitive. It knows the difference

156+Let's compile an example `hoon` from the last subsection into Nock.

132−between no whitespace, one-space, and more-space. But all cases

157+Try the following in Dojo:

133−of more-space mean the same thing. Flat syntax uses one-space,

134−tall syntax more-space.

135

158

136−As an example, the regular flat keyword syntax `:call(a b)` means

159+(~(mint ut %noun) %noun [%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]])

137−the same thing as the flat rune syntax `%-(a b)`, the tall

138−keyword syntax

139

160

140−```

161+### <a name="-type">`type`</a> (type, as range)

141−:call a

142−b

143−```

144−or the tall rune syntax (here on one line, with double spaces):

145−```

146−%- a b

147−```

148

162

149−### <a name="span">`span`</a> (type, as range)

163+A `type` defines a set (finite or infinite) of nouns and ascribes

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

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

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

150

167

151−A `span` is a Hoon type. It defines a set (finite or

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

152−infinite) of nouns and ascribes some semantics to it. There is

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

153−no syntax for spans; they are always defined by inference (ie, by

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

154−[`mint`](#mint)), usually using a constructor (`mold`).

171+of the simpler built-in types.

155

172

156−### `gate` (function)

173+### <a name="-gate">`gate`</a> (function)

157

174

158A `gate` is a Hoon function (lambda or closure). Other

175A `gate` is a Hoon function (lambda or closure). Other

159constructs in Urbit are functions in the mathematical sense -- for

176constructs in Urbit are functions in the mathematical sense -- for

@@ -161,7 +178,7 @@ instance, a Nock formula is also a function. But a gate is not a

161formula. The gate's argument is its *sample*; the result is its

178formula. The gate's argument is its *sample*; the result is its

162*product*.

179*product*.

163

180

164−### `core` (object)

181+### <a name="-core">`core`</a> (object)

165

182

166A `core` has no exact equivalent in conventional languages, but

183A `core` has no exact equivalent in conventional languages, but

167the closest equivalent is an object. An object has methods; a

184the closest equivalent is an object. An object has methods; a

@@ -173,55 +190,62 @@ A gate is a special case of a core: a core with one arm, whose

173name is the empty string. The shape of a core is `[battery

190name is the empty string. The shape of a core is `[battery

174payload]`, where *battery* is a tree of Nock formulas

191payload]`, where *battery* is a tree of Nock formulas

175

192

176−### `mold` (type, as constructor)

193+### <a name="-mold">`mold`</a> (constructor)

177

194

178A `mold` is a constructor function (`gate`). Its sample is any

195A `mold` is a constructor function (`gate`). Its sample is any

179noun; its product is a structured noun. A mold is idempotent;

196noun; its product is a structured noun. A mold is idempotent;

180`(mold (mold x))` always equals `(mold x)`.

197`(mold (mold x))` always equals `(mold x)`.

181

198

182−Since there's no such thing as a [`span`](#span) declaration, we use molds

199+Because there's no such thing as a [`type`](#-type) declaration,

183−to define useful spans by example; we also use them to validate

200+we use molds to define useful types by example; we also use them

184−untrusted network input.

201+to validate untrusted network data.

185

202

186−### `face` (named variable)

203+### <a name="-face">`face`</a> (named variable)

187

204

188In a conventional language, we have a scope, environment or

205In a conventional language, we have a scope, environment or

189−symbol table. Declaring a variable, like `var foo: atom`, adds

206+symbol table. Declaring a variable, like e.g. `int foo = 3`,

190−the name `foo` to the table with type `atom`.

207+adds the name `foo` to the table with type `int`.

191

208

192−The Hoon equivalent is `:var foo atom`. But Hoon has a

209+The Hoon analogue is `=/(foo atom 3 ...)`, where `foo` is a `face`

210+and `atom` is the type. But Hoon has a homoiconic heap; there is no

193−homoiconic heap; there is no inscrutable scope or environment.

211+inscrutable scope or environment. There is just the subject, which

194−There is just the subject, which is one noun. To "declare a

212+is one noun. To "declare a variable" is to make a cell

195−variable" is to make a cell `[variable old-subject]`, and use it

213+`[variable old-subject]`, and use that as the subject of the next

196−as the subject of the [`twig`](#twig) below.

214+expression.

197

215

198−So the labe[`twig`](#twig)l `foo` isn't a key in a symbol table; it's in the

216+The label `foo` isn't a key in a symbol table; it's stored as a kind

199−type ([`span`](#span)) of the new value. It's not a variable named `foo`,

217+of metadata, in the type ([`type`](#-type)) of the new value. It's not

200−whose value is of type `atom`; it's a subtree of type `foo:atom`.

218+a variable named `foo`, whose value is of type `atom`; it's a subtree

219+of type `foo:atom`.

201

220

202−### <a name="limb">`limb`</a> (attribute or variable reference)

221+### <a name="-limb">`limb`</a> (attribute or variable reference)

203

222

204−A [`limb`](../twig/limb/limb), like `foo`, is Hoon's equivalent of a variable

223+A [`limb`](../twig/limb/limb/), like `foo`, is Hoon's equivalent of a variable

205−reference. A limb is a [`twig`](#twig); given a subject [`span`](#span),

224+reference. A limb is a [`hoon`](#-hoon); given a subject [`type`](#-type),

206−[`mint`](#mint) resolves it to a Nock formula and a product [`span`](#span).

225+[`mint`](#-mint) resolves it to a Nock formula and a product [`type`](#-type).

207

226

208−To resolve limb `foo`, [`mint`](#mint) searches the subject depth-first,

227+To resolve limb `foo`, [`mint`](#-mint) searches the subject depth-first,

209head-first for either a `face` named `foo`, or a `core` with the

228head-first for either a `face` named `foo`, or a `core` with the

210arm `foo`. If it finds a face, the product is a *leg*, or

229arm `foo`. If it finds a face, the product is a *leg*, or

211subtree of the subject. If it finds a core, it computes the arm

230subtree of the subject. If it finds a core, it computes the arm

212−formula with that core as the subject.

231+formula with that core as the subject. A limb can also be a slot

232+(direct tree address), like `+15`.

233+

234+The hoon compiler always resolves a limb to a tree axis lookup,

235+regardless of the kind of limb.

213

236

214−A limb can also be a slot (direct tree address), like `+15`.

237+`boo:[foo=12 baz=23 boo=34]` evaluates to `34`.

238+`+6:[foo=12 baz=23 boo=34]` evaluates to `baz=23`.

215

239

216−### `wing` ([`limb`](#limb) path)

240+### <a name="-wing">`wing`</a> ([`limb`](#-limb) path)

217

241

218−A [wing](../twig/limb/wing) is a list of limbs. Like attribute references in a

242+A [wing](../twig/limb/wing/) is a list of limbs. Like attribute

219−conventional language, it uses the syntax `a.b.c`, but inside

243+references in a conventional language, it uses the syntax `a.b.c`,

220−out: Hoon `a.b.c` means "a within b within c", the equivalent of

244+but inside out: Hoon `a.b.c` means "a within b within c", the equivalent

221−`c.b.a` in any other language. All limbs but the last, here `a`,

245+of `c.b.a` in any other language. All limbs but the last, here `a`,

222must be legs.

246must be legs.

223

247

224−### `mark` (type, as protocol name)

248+### <a name="-mark">`mark`</a> (type, as protocol name)

225

249

226A `mark` (really an Arvo concept, not a Hoon concept) is Urbit's

250A `mark` (really an Arvo concept, not a Hoon concept) is Urbit's

227version of a MIME type, if a MIME type was an executable

251version of a MIME type, if a MIME type was an executable

docs/hoon/demo.md+52−42

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

1---

2navhome: /docs/

3−sort: 11

3+sort: 12

4next: true

5title: Demo

6---

@@ -11,68 +11,78 @@ Here's everyone's favorite whiteboard example, FizzBuzz. Each

11line is commented with its number:

13```

14−|= end/atom :: 1

14+|= end=@ud :: 1

15−=/ count 1 :: 2

15+=/ count=@ud 1 :: 2

16−|- :: 3

16+|- :: 3

17−^- (list tape) :: 4

17+^- (list tape) :: 4

18−?: =(end count) :: 5

18+?: =(end count) :: 5

19− ~ :: 6

19+ ~ :: 6

20−:- :: 7

20+:- :: 7

21− ?: =(0 (mod count 15)) :: 8

21+ ?: =(0 (mod count 15)) :: 8

22− "FizzBuzz" :: 9

22+ "FizzBuzz" :: 9

23− ?: =(0 (mod count 5)) :: 10

23+ ?: =(0 (mod count 5)) :: 10

24− "Fizz" :: 11

24+ "Fizz" :: 11

25− ?: =(0 (mod count 3)) :: 12

25+ ?: =(0 (mod count 3)) :: 12

26− "Buzz" :: 13

26+ "Buzz" :: 13

27− (pave !>(count)) :: 14

27+ (scow %ud count) :: 14

28−$(count (add 1 count)) :: 15

28+$(count (add 1 count)) :: 15

29```

31Hoon is a functional language. FizzBuzz is usually defined as a

32−side effect, but officially Hoon has no side effects. This code

32+side effect, but officially Hoon has no side effects. Accordingly,

33−will *return* a list of strings, not *print* a list of strings.

33+this code will *produce* a list of strings, not *print* a list of

34−(Of course, if you run this code from the Urbit `dojo` (shell) you

34+strings. (Of course, if you run this code from the Urbit

35−will be able to see the product.)

35+[_Dojo_](../../using/shell) (shell) you will be able to see the

36+product.)

37The code produces a list in which each item is either a number

38The code produces a list in which each item is either a number

38(as a string), "Fizz", "Buzz", or "Fizzbuzz". The value `~` is

39(as a string), "Fizz", "Buzz", or "Fizzbuzz". The value `~` is

39"null" and indicates the end of the list.

40"null" and indicates the end of the list.

41−Line 1 uses the `|=`

42−*[rune](https://urbit.org/docs/about/glossary#rune)* to define a

42+Line 1 uses the _[rune](../../about/glossary#rune)_ `|=` (pronounced

43−function of one argument, `end`, which is of the type `atom` (i.e.

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−an unsigned integer).

45+type `@ud`, an unsigned decimal number.

47+Line 2 uses the rune `=/` (pronounced "tis-fas") to declare a variable,

46−Line 2 declares a variable, `count`, with initial value `1`.

48+`count` of the unsigned decimal number type, with initial value `1`.

48−Line 3 begins a loop.

50+Line 3 uses the rune `|-` ("bar-hep") to begin a loop.

50Line 4 defines the product of the loop as a list of `tape`s.

52Line 4 defines the product of the loop as a list of `tape`s.

51(A `tape` is a list of characters, one of Hoon's two string

53(A `tape` is a list of characters, one of Hoon's two string

52−types.) The `^-` rune is used for defining the product type the function

54+types.) The rune `^-` ("ket-hep") is used for defining

53−is to return.

55+the type of value the function must produce.

55−Line 5 uses the `?:` rune, which is a conditional. This line

57+Line 5 uses the rune `?:` ("wut-tis"), which is your classic "if, then,

56−checks whether `count` equals `end`. If so, line 6 (and the

58+else" conditional. The "if" clause uses the irregular form of the rune

59+`.=` ("dot-tis"), one of the fundamental [Nock](../../nock/definition)

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`

62+(no, 1) and consequently compute the "then" or "else" clause

63+respectively.

64+

65+If the values of `count` and `end` are equal, line 6 (and the whole loop)

57−whole loop) returns the value `~`. The list is finished. If not,

66+returns the value `~`. The list is finished.

67+

68+If not, line 7 uses the rune `:-` ("col-hep") to produce a 'cell', which

58−line 7 produces an ordered pair. This pair will be: (a) the next

69+is an ordered pair of Hoon values. This pair will be: (a) the next item

59−item in the list, determined by lines 8-14; and (b) the rest of

70+in the list, determined by more `?:` conditionals in lines 8-14; and (b)

60−the list, determined by line 15.

71+the rest of the list, determined by line 15.

62(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

63"Buzz", if the respective tests hit; otherwise, it's

74"Buzz", if the respective tests hit; otherwise, it's

64(ii) the number in question, `count`. In case (ii), line 14

75(ii) the number in question, `count`. In case (ii), line 14

65−makes `count` into a `tape`, first by using `!>` to produce a

76+uses the Hoon standard library function `++scow` to take the value of

66−pair: runtime type of `count`, and `count` itself. `pave` is a

77+`count`, of type `@ud`, and pretty-print it as a `tape`.

67−Hoon function that converts the type-value pair to a `tape`

68−(like C `sprintf()`).

70(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

71−produced at line 15, which uses `$()` to repeat the loop (like

80+produced 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)

72−Clojure `recur`), with `count` incremented.

82+with `count` incremented.

74You can test this code by mounting your home desk with

84You can test this code by mounting your home desk with

75−`|mount %` from the dojo; saving the above code as

85+`|mount %` from the Dojo; saving the above code as

76`home/gen/fizzbuzz.hoon` in your Urbit

86`home/gen/fizzbuzz.hoon` in your Urbit

77−[pier](https://urbit.org/docs/about/glossary#pier); then typing

87+[pier](../../about/glossary#pier); then typing

78`+fizzbuzz 100` in the dojo.

88`+fizzbuzz 100` in the dojo.

docs/hoon/reference.md+3−3

@@ -1,12 +1,12 @@

1---

2navhome: /docs/

3sort: 21

4−title: Twig reference

4+title: Expression reference

5---

7−# Twig reference

7+# Expression reference

9−#### A catalog of all twig stems:

9+#### A catalog of expressions:

11<div class="book">

docs/hoon/syntax.md+27−26

@@ -111,10 +111,10 @@ line comment at column 57.

111## Expressions and Runes

112

113Each regular Hoon expression begins with a

114−[rune](https://urbit.org/docs/about/glossary#rune). A rune is a pair

114+[rune](../about/glossary/#-rune). A rune is a pair

115of ASCII punctuation marks (a digraph)—e.g., `:-`. The first

116glyph in the rune indicates the category—e.g., `:` runes make

117−[cells](https://urbit.org/docs/about/glossary#cell) (i.e., ordered

117+[cells](../about/glossary/#-cell) (i.e., ordered

118pairs). We pronounce runes using their glyph names—for `:-`,

119we say "colhep".

120

@@ -126,29 +126,30 @@ kind of subexpressions depend on the rune used.

1263

127```

128

129−This twig 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

130subexpressions following the `:-` in syntactically correct Hoon code,

131the 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 sometimes called

134+Hoon expressions are just called

135−[twigs](https://urbit.org/docs/about/glossary#twig). You'll find that

135+[hoons](../about/glossary/#-twig), because a rune's subexpression can itself

136−Hoon code has a tree-like structure, so you can think of the various

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−expressions as twigs of the tree. The subexpressions following the

138+file being composed of multiple hoons. The subexpressions following the

138−rune are sometimes called the *children* of that twig.

139+rune are sometimes called the *children* of that hoon.

139

140

140## Tall and flat forms

141## Tall and flat forms

141

142

142There are two kinds of Hoon expression syntax: *tall* and *flat*.

143There are two kinds of Hoon expression syntax: *tall* and *flat*.

143−Most runes can be used in both tall and flat twigs. Tall twigs can

144+Most runes can be used in both tall and flat twigs. Tall hoons can

144−contain flat twigs, but not vice versa.

145+contain flat hoons, but not vice versa.

145

146

146The `:-` expression in the last subsection was in tall form. Here's

147The `:-` expression in the last subsection was in tall form. Here's

147the flat equivalent:

148the flat equivalent:

148

149

149`:-(25 3)`

150`:-(25 3)`

150

151

151−Visually, a tall twig looks like a "statement" and a flat twig

152+Visually, a tall hoon looks like a "statement" and a flat hoon

152like an "expression," preserving the attractive visual shape of

153like an "expression," preserving the attractive visual shape of

153procedural code without the nasty side effects.

154procedural code without the nasty side effects.

154

155

@@ -172,7 +173,7 @@ follow, and returns a boolean. Above is the tall, regular form of

172

173

173`=(22 23)`

174`=(22 23)`

174

175

175−Some twigs have *only* irregular forms.

176+Some hoons have *only* irregular forms.

176

177

177## Tall regular form

178## Tall regular form

178

179

@@ -182,14 +183,14 @@ that are the number and types of subexpressions appropriate for

182that rune. Each subexpression is separated from its neighboring

183that rune. Each subexpression is separated from its neighboring

183subexpressions by a `gap`.

184subexpressions by a `gap`.

184

185

185−Let's call everything in the twig after the initial rune the twig

186+Let's call everything in the hoon after the initial rune the hoon

186*body*. There are four body subtypes: *fixed*, *running*, *jogging*,

187*body*. There are four body subtypes: *fixed*, *running*, *jogging*,

187−and *[battery](https://urbit.org/docs/about/glossary#battery)*.

188+and *[battery](../about/glossary/#-battery)*.

188

189

189Runes with a *fixed* number of subexpressions self-terminate. For

190Runes with a *fixed* number of subexpressions self-terminate. For

190instance, the `:-` and `.=` runes each have two subexpressions

191instance, the `:-` and `.=` runes each have two subexpressions

191−and are self-terminating. Otherwise the twig is terminated by both

192+and are self-terminating. Otherwise the hoon is terminated by both

192−a `gap`, then either `==` (*running* or *jogging*, most twigs) or

193+a `gap`, then either `==` (*running* or *jogging*, most hoons) or

193`--` (*battery*).

194`--` (*battery*).

194

195

195The *running* body has a list of *children* (i.e., subexpressions).

196The *running* body has a list of *children* (i.e., subexpressions).

@@ -217,7 +218,7 @@ until you know what you're doing. Here are the conventions:

217

218

218Twig bodies with *fixed* fanout use "backstep" indentation, which

219Twig bodies with *fixed* fanout use "backstep" indentation, which

219slopes backward and to the right by two spaces per line. The first

220slopes backward and to the right by two spaces per line. The first

220−twig child is two spaces after the end of the rune.

221+hoon child is two spaces after the end of the rune.

221

222

222Some *1-fixed*, *2-fixed*, *3-fixed* and *4-fixed* examples:

223Some *1-fixed*, *2-fixed*, *3-fixed* and *4-fixed* examples:

223

224

@@ -238,12 +239,12 @@ r

238s

239s

239```

240```

240

241

241−In optimal usage of backstep indentation, the most complicated twigs

242+In optimal usage of backstep indentation, the most complicated hoons

242are at the bottom, keeping code flow vertical rather than diagonal.

243are at the bottom, keeping code flow vertical rather than diagonal.

243

244

244### Conventions: *running*

245### Conventions: *running*

245

246

246−A *running* twig body (a simple child list) puts the first child two

247+A *running* hoon body (a simple child list) puts the first child two

247spaces after the end of the rune, and the following children straight

248spaces after the end of the rune, and the following children straight

248down:

249down:

249

250

@@ -260,7 +261,7 @@ A *running* example:

260

261

261### Conventions: *jogging*

262### Conventions: *jogging*

262

263

263−A *jogging* twig body (a list of child pairs) is like a running

264+A *jogging* hoon body (a list of child pairs) is like a running

264body, but with a pair of children on each line, separated by

265body, but with a pair of children on each line, separated by

265two spaces. Most jogging bodies start with a *fixed* sequence;

266two spaces. Most jogging bodies start with a *fixed* sequence;

266the first jogging pair is below and two steps backward from the

267the first jogging pair is below and two steps backward from the

@@ -295,9 +296,9 @@ A *tall jogging* example (preceded by *1-fixed* `p`):

295### Conventions: *battery*

296### Conventions: *battery*

296

297

297A *battery* body has a list of symbol-child pairs, for the

298A *battery* body has a list of symbol-child pairs, for the

298−[battery](https://urbit.org/docs/about/glossary#battery)

299+[battery](../about/glossary/#-battery)

299of a

300of a

300−[core](https://urbit.org/docs/about/glossary#core). A

301+[core](../about/glossary/#-core). A

301conventional example:

302conventional example:

302

303

303```

304```

@@ -318,7 +319,7 @@ Flat regular form starts with the rune, followed by `pal`, `(`

318are separated by `ace` (one space), followed by `par`, `)` (right

319are separated by `ace` (one space), followed by `par`, `)` (right

319parenthesis).

320parenthesis).

320

321

321−A twig in flat form, `:if`, `?:`, `{$if p/twig q/twig r/twig}`:

322+A hoon in flat form, `?:` ("wutcol"), `[%if p=hoon q=hoon r=hoon]`:

322

323

323`?:(p q r)`

324`?:(p q r)`

324

325

@@ -355,7 +356,7 @@ appropriate.

355

356

356In the *ultralapidary* naming style, labels are single letters,

357In the *ultralapidary* naming style, labels are single letters,

357starting in order of construction from `a`, or within a tuple

358starting in order of construction from `a`, or within a tuple

358−[mold](https://urbit.org/docs/about/glossary#mold) `p`. Hoon

359+[mold](../about/glossary/#-mold) `p`. Hoon

359uses single-letter names for the same reason Algol style

360uses single-letter names for the same reason Algol style

360languages pass arguments by order, rather than keyword. Naming

361languages pass arguments by order, rather than keyword. Naming

361items by order makes sense when there are no more than three or

362items by order makes sense when there are no more than three or

@@ -384,7 +385,7 @@ long names and/or kebab-case.

384

385

385If you came all this way to learn how to write apps, you're all

386If you came all this way to learn how to write apps, you're all

386set. This is about all you need to know to start getting your

387set. This is about all you need to know to start getting your

387−hands dirty. Refer back here or to the [standard library](../../hoon/library) when

388+hands dirty. Refer back here or to the [standard library](../library/) when

388−needed, but for now, move on to [Arvo](../../arvo) to continue learning.

389+needed, but for now, move on to [Arvo](../../arvo/) to continue learning.

389

390

390If, however, good enough is *not* enough, feel free to dive deeper:

391If, however, good enough is *not* enough, feel free to dive deeper: