e59df05 · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

Formatting and additions: /docs/about/glossary/, /docs/hoon/demo/ /syntax/ /concepts/

e59df05Keaton 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+37−38

@@ -10,7 +10,7 @@ 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−*variable* or *function*, that map cleanly onto its semantics.

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

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

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

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

32## Concepts

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

35−[`hoon`](#hoon) (AST node), [`mint`](#mint) (compiler),

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

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

37(protocol).

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

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

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

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

@@ -45,17 +45,18 @@ simpler (Lisp atoms effectively have dynamic type bits).

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

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

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

48+d]]]`.

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

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

52freely than Lisp; only genuinely iterative structures are

53null-terminated lists.

55−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

56−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

57−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

58−(Hoon syntax uses `.` to break integer atoms in the German style.)

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

59+aren't.)

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

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

61scheme 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

@@ -66,7 +67,7 @@ detect pointer equivalence. Nouns are generally implemented

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

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

67help with equality testing and associative containers.

68help with equality testing and associative containers.

69−### `nock` (interpreter)

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

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

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

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

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

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

78## Compilation concepts

79## Compilation concepts

80−### <a name="hoon">`hoon`</a> (AST node)

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

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

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

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

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

@@ -113,11 +114,11 @@ The result should be:

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

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

114```

115```

115

116

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

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

117

118

118−[`mint`](#mint) is the Hoon compiler. It maps a cell `[type hoon]`

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

119−to a cell `[type nock]`, where a [`type`](#type) is type

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

120−information, a [`hoon`](#hoon) is a parsed expression (AST), and a

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

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

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

122and a parsed source expression; it produces a product type and an

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

123executable formula.

124executable formula.

@@ -153,25 +154,23 @@ type is a subset of the input type. If not, mint halts with a

153`nest-fail` crash.

154`nest-fail` crash.

154

155

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

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

156−Try the following in `:dojo`:

157+Try the following in Dojo:

157

158

158−```

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

160−```

161

160

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

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

163

162

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

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

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

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

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

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

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

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

168

167

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

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

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

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

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

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

172of the simpler built-in types.

171of the simpler built-in types.

173

172

174−### `gate` (function)

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

175

174

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

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

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

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

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

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

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

180*product*.

179*product*.

181

180

182−### `core` (object)

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

183

182

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

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

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

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

@@ -191,17 +190,17 @@ A gate is a special case of a core: a core with one arm, whose

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

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

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

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

193

192

194−### `mold` (constructor)

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

195

194

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

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

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

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

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

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

199

198

200−Because there's no such thing as a [`type`](#type) declaration,

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

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

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

202−to validate untrusted network input.

201+to validate untrusted network data.

203

202

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

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

205

204

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

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

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

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

@@ -211,21 +210,21 @@ The Hoon analogue is `=/(foo atom 3 ...)`, where `foo` is a `face`

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

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

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

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

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

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

214−`[variable old-subject]`, and use thatas the subject of the next

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

215expression.

214expression.

216

215

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

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

218−of metadata, in the type ([`type`](#type)) of the new value. It's not

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

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

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

220of type `foo:atom`.

219of type `foo:atom`.

221

220

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

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

223

222

224−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

225−reference. A limb is a [`hoon`](#hoon); given a subject [`type`](#type),

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

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

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

227

226

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

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

229head-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

230arm `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

231subtree 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

@@ -238,15 +237,15 @@ regardless of the kind of limb.

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

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

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

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

240

239

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

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

242

241

243−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

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

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

245−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

246−`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`,

247must be legs.

246must be legs.

248

247

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

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

250

249

251A `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

252version 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. Accordingly,

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

33−this code will *return* 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 `dojo`

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

35−(shell) you 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+["bar-tis"](../syntax/#-glyphs-and-characters)) to define a function

43−function that takes one argument, labelled `end`. The argument

44+that takes one argument, labelled `end`. The argument must be of the

44−is of the type `atom` (i.e. 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 type of data the

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

53−function 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 a 'cell', which is an ordered pair. The pair will

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

59−be: (a) the next item in the list, determined by lines 8-14; and

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

60−(b) the rest of 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/syntax.md+57−61

@@ -111,50 +111,46 @@ 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

121Each rune is followed by one or more subexpressions. The number and

122−kind of subexpressions depend on which rune is used.

122+kind of subexpressions depend on the rune used.

123

124```

125:- 25

1263

127```

128

129−The `:-` rune is always followed by two 'value' subexpressions to

129+This Hoon uses `:-` to produce a cell: `[25 3]`. There are always two

130−produce a cell: `[25 3]`. The first subexpression, when evaluated,

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

131−becomes the *head* (i.e., the left) of the cell, and the second

131+the first of which, when evaluated, becomes the *head* (i.e., the left)

132−becomes the *tail* (i.e., the right).

132+and the second of which becomes the *tail* (i.e., the right).

133

134−There are two kinds of expressions in Hoon: *value* and *pattern*.

134+Hoon expressions are just called

135−Value expressions evaluate to any sort of data. They can be as simple

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

136−as `25`, or they may require more computation, as in `(add 22 3)`. The

136+be a Hoon expression (i.e. another rune). You'll start to see this tree-like,

137−`:-` expression above is itself a value expression, as are the vast

137+recursive structure the more you program in Hoon. You can think of one Hoon

138−majority of Hoon expressions.

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

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

139

140

140−A pattern expression must be a *mold*, which we'll explain a bit

141+## Tall and flat forms

141−[later](https://urbit.org/docs/hoon/basic).

142

143−## Tall and flat styles

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

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

145+contain flat hoons, but not vice versa.

144

146

145−There are two styles of Hoon expression syntax: *tall* and *flat*.

146−Most runes can be used in both tall and flat styles. Tall expressions

147−are (typically) multi-line, but flat expressions must not have line

148−breaks in them. Tall expressions may contain flat ones, but not vice

149−versa.

150−

151−The `:-` expression in the last subsection was in tall style. Here's

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

152the flat equivalent:

148the flat equivalent:

153

149

154`:-(25 3)`

150`:-(25 3)`

155

151

156−Visually, the tall style looks more "statement"-like and flat-style

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

157−looks "expression"-like, preserving the attractive visual shape of

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

158procedural code without the nasty side effects.

154procedural code without the nasty side effects.

159

155

160## Regular and irregular forms

156## Regular and irregular forms

@@ -164,7 +160,7 @@ There is a regular flat form and a regular tall form; most runes

164have both kinds of implementation. All tall forms are regular.

160have both kinds of implementation. All tall forms are regular.

165

161

166Some runes also have *irregular forms*, which follow no

162Some runes also have *irregular forms*, which follow no

167−general principles at all. All irregular forms are flat.

163+principles at all. All irregular forms are flat.

168

164

169```

165```

170.= 22

166.= 22

@@ -177,51 +173,52 @@ follow, and returns a boolean. Above is the tall, regular form of

177

173

178`=(22 23)`

174`=(22 23)`

179

175

180−Some kinds of expression have *only* irregular forms.

176+Some hoons have *only* irregular forms.

181

177

182## Tall regular form

178## Tall regular form

183

179

184Tall regular forms start with a rune followed by a `gap`.

180Tall regular forms start with a rune followed by a `gap`.

185−(Remember, a `gap` is any whitespace other than `ace`, or a line

181+(Remember, a `gap` is any whitespace other than `ace`.) After

186−break.) After that are the number and types of subexpressions

182+that are the number and types of subexpressions appropriate for

187−appropriate for that rune. Each subexpression is separated from

183+that rune. Each subexpression is separated from its neighboring

188−its neighboring subexpressions by a `gap`.

184+subexpressions by a `gap`.

189

185

190−Everything after the initial rune in an expression is called the

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

191−*body*. There are four body types: *fixed*, *running*, *jogging*,

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

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

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

193

189

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

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

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

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

196−and are self-terminating. Otherwise the body is terminated by a

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

197−`gap` followed by either `==` (*running* or *jogging*, most runes)

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

198−or `--` (*battery*).

194+`--` (*battery*).

199

195

200−The *running* body is a list of *children* (i.e., subexpressions).

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

201−The *jogging* body is a list of child pairs, where the members of

197+The *jogging* body has a list of child pairs, where the members of

202each pair are separated by a `gap`. The *battery* body is

198each pair are separated by a `gap`. The *battery* body is

203−a list of symbol-child pairs, each separated by a `gap`. See below

199+a list of symbol-child pairs, separated by a gap, prefixed by `++`

204−for examples of each body type.

200+and then a gap.

205

201

206This definition is enough to write Hoon that will parse. But

202This definition is enough to write Hoon that will parse. But

207writing code with optimal whitespace management requires some

203writing code with optimal whitespace management requires some

208additional informal conventions.

204additional informal conventions.

209

205

210Whitespace design in Hoon is an art, not a science. It involves

206Whitespace design in Hoon is an art, not a science. It involves

211−both tall/flat style switches and well-shaped gaps. (Hoon layout

207+both tall/flat mode switches and well-shaped gaps. (Hoon layout

212could probably be done automatically with reasonable quality.

208could probably be done automatically with reasonable quality.

213But it would at least take machine learning, not a rule engine.)

209But it would at least take machine learning, not a rule engine.)

214

210

215There are only two real *rules* in Hoon whitespace design: don't

211There are only two real *rules* in Hoon whitespace design: don't

216go past 80 characters, and don't use (completely) blank lines.

212go past 80 characters, and don't use (completely) blank lines.

217−Otherwise, if it looks good and is easy to read, it's fine. The

213+Otherwise, if it looks good and is easy to read, it's good. The

218best way to learn the art is to do everything by convention

214best way to learn the art is to do everything by convention

219until you know what you're doing. Here are the conventions:

215until you know what you're doing. Here are the conventions:

220

216

221### Conventions: *fixed*

217### Conventions: *fixed*

222

218

223−Expressions with *fixed* bodies use "backstep" indentation, which

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

224−slopes backward and to the right by two spaces per line.

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

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

225

222

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

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

227

224

@@ -242,15 +239,14 @@ r

242s

239s

243```

240```

244

241

245−In optimal usage of backstep indentation, the most complicated

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

246−expressions are at the bottom, keeping code flow vertical rather than

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

247−diagonal.

248

244

249### Conventions: *running*

245### Conventions: *running*

250

246

251−A *running* body (a simple child list of arbitrary length) puts the

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

252−first child two spaces after the end of the rune, and the following

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

253−children straight down:

249+down:

254

250

255A *running* example:

251A *running* example:

256

252

@@ -265,10 +261,10 @@ A *running* example:

265

261

266### Conventions: *jogging*

262### Conventions: *jogging*

267

263

268−A *jogging* body (a list of child pairs of arbitrary length) is like

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

269−a running 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

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

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

271−the first pair is below and two steps backward from the

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

272last fixed child.

268last fixed child.

273

269

274There are two jogging conventions: *flat* (pair on one line) and

270There are two jogging conventions: *flat* (pair on one line) and

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

300### Conventions: *battery*

296### Conventions: *battery*

301

297

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

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

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

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

304of a

300of a

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

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

306conventional example:

302conventional example:

307

303

308```

304```

@@ -320,10 +316,10 @@ conventional example:

320

316

321Flat regular form starts with the rune, followed by `pal`, `(`

317Flat regular form starts with the rune, followed by `pal`, `(`

322(left parenthesis), followed by a body whose subexpressions

318(left parenthesis), followed by a body whose subexpressions

323−are all separated by `ace`s (single spaces), followed by `par`,

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

324−`)` (right parenthesis).

320+parenthesis).

325

321

326−A expression in flat form, `?:`, which is 3-fixed:

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

327

323

328`?:(p q r)`

324`?:(p q r)`

329

325

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

360

356

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

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

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

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

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

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

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

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

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

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

366items 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

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

389

385

390If 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

391set. 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

392−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

393−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.

394

390

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

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