65a84bf · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on master help sign in

cleaned up twig terminology. Every instance is gone except in

65a84bfRobert9 years ago

docs/arvo/basic.md+22−22

compare with master

unifiedsplit

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

20## Installation

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

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

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

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

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

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

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

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

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

28−if you're on a

28+if you're on a

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

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

30otherwise experiencing problems with the network install.

32### Network install

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

107 ::

108 |%

109 ++ three

110− |= a/@

110+ |= a/@

111− =| b/@

111+ =| b/@

112 |- ^- @u

113 ?: (lth a b)

114 0

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

116 ::

117 ++ five

118− |= a/@

118+ |= a/@

119− =| b/@

119+ =| b/@

120 |- ^- @

121 ?: (lte a b)

122 0

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

124− $(b (add b 5))

124+ $(b (add b 5))

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

126 ::

127− ++ sum

127+ ++ sum

128 |= a/@u

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

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

130 --

131

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

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

190### Lines 14-37

191

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

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

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

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

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

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

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

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

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

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

199

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

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

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

210 --

211

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

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

213takes two children:

214

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

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

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

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

236

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

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

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

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

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

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

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

253initialized to `0`.

254

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

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

256point. More on this later.

257

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

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

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

260

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

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

299 =(a b) test equality

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

301

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

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

303

304### New material

305

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

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

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

326

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

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

328

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

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

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

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

10Our typed and marked computation engine.

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

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

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

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

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

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

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

100### `%reef`

101

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

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

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

104

105### `%ride`

106

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

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

108

109### `%vale`

110

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

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

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

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

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

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

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

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

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

49is reloaded.

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

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

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

81 [%reef ~] :: kernel reef

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

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

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

84 == ::

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

96 ++ calx :: concrete cache line

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

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

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

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

100 == ::

101

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

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

107compiling the given cage at the given location.

108

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

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

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

111vase produced by slapping them.

112

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

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

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

160

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

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

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

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

164

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

181### `++horn`

182

183 ++ horn :: resource tree

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

203only give a description of the data structure itself.

204

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

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

206subject.

207

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

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

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

233in the directory.

234

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

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

236the horn.

237

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

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

246### `++hoop`, body

247

248 ++ hoop :: source in hood

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

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

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

251 == ::

252

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

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

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

360 [%reef ~] :: kernel reef

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

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

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

363 == ::

364

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

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

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

411

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

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

413`%noun`.

414

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

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

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

482

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

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

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

485

486 ++ hoot

487 ;~ pose

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

491

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

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

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

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

495

496 ++ hoof

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

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

529 (stag %& tall:vez)

530 ==

531

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

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

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

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

534

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

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

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

537

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

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

600 ;~(pfix gap tall:vez)

601

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

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

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

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

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

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

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

606

607 ++ day

608 %+ rail

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

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

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

667

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

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

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

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

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

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

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

672

673 ++ see

674 %+ rail

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

701

702 ++ meow :: assemble

703 |= [how=beam arg=heel]

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

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

705 zog=(set term) :: structure guard

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

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

707 lot=(list term) :: library stack

708 zeg=(set term) :: library guard

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

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

710 hol=? :: horns allowed?

711 ==

712 |%

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

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

716virtual path extension, of the file.

717

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

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

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

720a core at the top of the file.

721

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

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

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

726

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

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

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

729series of cores after the structure core.

730

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

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

741enforces that our library dependency graph is a DAG.

742

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

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

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

745

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

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

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

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

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

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

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

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

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

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

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

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

917 ==

918

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

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

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

921file.

922

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

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

959the product.

960

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

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

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

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

963

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

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

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

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

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

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

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

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

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

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

991

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

993current context.

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

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

1005

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

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

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

1008`++flaw`.

1009

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

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

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

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

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

1083−that we can isolate the new body twigs.

1083+that we can isolate the new body hoons.

1084

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

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

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

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

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

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

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

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

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

1093

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

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

1135

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

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

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

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

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

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

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

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

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

1148

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

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

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

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

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

1153−we can isolate the new body twigs.

1153+we can isolate the new body hoons.

1154

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

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

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

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

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

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

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

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

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

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

1163

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

1165

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

1180 (fine cof fin)

1181

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

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

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

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

1185

1186 ++ able :: assemble preamble

1187− ^- twig

1187+ ^- hoon

1188 :+ %tsgr

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

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

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

1191

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

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

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

1198

1199 ++ maim :: slap

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

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

1201 ^- (bolt vase)

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

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

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

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

1205 ?- -.puz

1206 | (flaw cof p.puz)

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

1215we'll discuss the caching system.

1216

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

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

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

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

1220

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

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

1343 ?- -.hon

1344 %ape (maim cof bax p.hon)

1345

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

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

1347

1348 %arg

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

1350 |= [cof=cafe gat=vase]

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

1352

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

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

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

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

1356

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

1549 (maul cof gat sam)

1550

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

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

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

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

1554

1555 %sic

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

1599 |= [cof=cafe gox=vase]

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

1601 |= [cof=cafe fin=vase]

1602− (fine cof fin)

1602+ (fine cof fin)

1603

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

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

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

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

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

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

1609

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

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

2346 ++ keel :: apply mutations

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

2348 ^- (bolt vase)

2349− %^ maim cof

2349+ %^ maim cof

2350 %+ slop suh

2351 |- ^- vase

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

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

2354− ^- twig

2354+ ^- hoon

2355 :+ %cncb [%& 2]~

2356 =+ axe=3

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

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

2358 ?~ yom ~

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

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

2361

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

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

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

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

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

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

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

2367axis 3 of whatever axis we were already at.

2368

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

2483 (fine cof %noun vax)

2484

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

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

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

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

2488

2489Lifecycle of a `%vale`

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

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

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

2534 |= [cof=cafe pro=vase]

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

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

2536 (fine cof (slot 6 pro))

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

2538

docs/arvo/subscriptions.md+11−11

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

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

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

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

14−that it's built into arvo.

14+that it's built into Arvo.

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

17`:source`:

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

137

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

139 the irregular wide form of the `?&`

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

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

141 logical `AND` on its two children.

142

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

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

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

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

146 on its two children.

147

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

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

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

150 `NOT` on its child.

151

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

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

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

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

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

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

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

157 of type `p`.

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

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

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

160

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

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

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

163

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

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

166 and `now`, the current time.

167

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

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

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

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

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

172

173

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

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

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

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

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

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

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

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

docs/hoon/demo.md+33−33

@@ -30,59 +30,59 @@ $(count (add 1 count)) :: 15

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

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

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

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

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

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

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

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

36product.)

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

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

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

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

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

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

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

43−["bar-tis"](../syntax/#-glyphs-and-characters)) to define a function

43+["bar-tis"](../syntax/#-glyphs-and-characters)) to define a function

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

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

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

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

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

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

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

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

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

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

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

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

55−the type of value the function must produce.

55+the type of value the function must produce.

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

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

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

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

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

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

60−instructions, to perform an equality test on the values of `count` and

60+instructions, to perform an equality test on the values of `count` and

61−`end`. This will produce either `%.y` (yes, the number 0) or `%.n`

61+`end`. This will produce either `%.y` (yes, the number 0) or `%.n`

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

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

63−respectively.

63+respectively.

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

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

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

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

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

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

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

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

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

73−(a) The head of the pair is: (i) "FizzBuzz", or "Fizz", or

73+(a) The head of the pair is: (i) "FizzBuzz", or "Fizz", or

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

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

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

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

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

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

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

79−(b) The tail of the pair—the rest of the output list—is

79+(b) The tail of the pair—the rest of the output list—is

80produced at line 15, which uses the irregular `$()` syntax for the rune

81−`%=` ("cen-tis") to repeat the loop set above (with the `|-` in line 3)

81+`%=` ("cen-tis") to repeat the loop set above (with the `|-` in line 3)

82−with `count` incremented.

82+with `count` incremented.

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

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

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

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

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

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

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

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

88`+fizzbuzz 100` in the dojo.

docs/hoon/library/4o.md+24−24

@@ -136,7 +136,7 @@ Used to build [tape]()s internally.

136Source

137------

138

139− ++ beer $|(@ [~ p=twig]) :: simple embed

139+ ++ beer $|(@ [~ p=hoon]) :: simple embed

140

141Examples

142--------

@@ -158,11 +158,11 @@ Source

158------

159

160 ++ beet $| @ :: advanced embed

161− $% [%a p=twig] :: take tape

161+ $% [%a p=hoon] :: take tape

162− [%b p=twig] :: take manx

162+ [%b p=hoon] :: take manx

163− [%c p=twig] :: take marl

163+ [%c p=hoon] :: take marl

164− [%d p=twig] :: take $+(marl marl)

164+ [%d p=hoon] :: take $+(marl marl)

165− [%e p=twig q=(list tuna)] :: element literal

165+ [%e p=hoon q=(list tuna)] :: element literal

166 == ::

167

168

@@ -226,8 +226,8 @@ Cases of arms by variance model.

226Source

227------

228

229− ++ foot $% [%ash p=twig] :: dry arm, geometric

229+ ++ foot $% [%ash p=hoon] :: dry arm, geometric

230− [%elm p=twig] :: wet arm, generic

230+ [%elm p=hoon] :: wet arm, generic

231 [%oak ~] :: XX not used

232 [%yew p=(map term foot)] :: XX not used

233 == ::

@@ -436,14 +436,14 @@ Source

436Examples

437--------

438

439−A `++wing` or `++twig`.

439+A `++wing` or `++hoon`.

440

441 > (ream '=+ a=4 ?-(a @ ~)')

442 [ %tsls

443 p=[%ktts p=p=%a q=[%dtzy p=%ud q=4]]

444 q

445 [ %wthz

446− p=[%.y p=~ q=~[%a]]

446+ p=[%.y p=~ q=~[%a]]

447 q=~[[p=[%axil p=[%atom p=~.]] q=[%bczp p=%null]]]

448 ]

449 ]

@@ -559,8 +559,8 @@ Source

559------

560

561 ++ tuna :: tagflow

562− [%d p=twig] :: dynamic list

562+ [%d p=hoon] :: dynamic list

563− [%e p=twig q=(list tuna)] :: element

563+ [%e p=hoon q=(list tuna)] :: element

564 [%f p=(list tuna)] :: subflow

565 == ::

566

@@ -568,7 +568,7 @@ Examples

568--------

569

570Leaf %a contains plain-text, %b an empty tag, %c a static list, %d a

571−dynamic list, %e a full node element containing a twig and a list of

571+dynamic list, %e a full node element containing a hoon and a list of

572tuna, and %f is a empty node.

573

574See also: [`++sail`]()

@@ -580,13 +580,13 @@ See also: [`++sail`]()

580

581List of expressions

582

583−List of [`++twig`]()s. In [`:*`](), for example, your contents is

583+List of [`++hoon`]()s. In [`:*`](), for example, your contents is

584a `++tusk`.

585

586Source

587------

588

589− ++ tusk (list twig) ::

589+ ++ tusk (list hoon) ::

590

591Examples

592--------

@@ -599,22 +599,22 @@ Examples

599

600

601***

602−### `++twig`

602+### `++hoon`

603

604Expression

605

606An expression, or AST.

607

608−See Twig section of Hoon reference

608+See Rune section of Hoon reference

609

610

611

612***

613### `++tyke`

614

615−List of 'maybe' twigs

615+List of 'maybe' hoons

616

617−List of [`++unit`]() [`++twig`](), or gaps left to be inferred, in [`++path`]()

617+List of [`++unit`]() [`++hoon`](), or gaps left to be inferred, in [`++path`]()

618parsing. When you use a path such as `/=main=/pub/src/doc` the path is in fact

619a `++tyke`, where the `=` are inferred from your current path.

620

@@ -622,7 +622,7 @@ a `++tyke`, where the `=` are inferred from your current path.

622Source

623------

624

625− ++ tyke (list (unit twig)) ::

625+ ++ tyke (list (unit hoon)) ::

626

627Examples

628--------

@@ -657,14 +657,14 @@ See also: `++seem`, `++vise`, `++type`

657***

658### `++tyre`

659

660−List, term to twig

660+List, term hoon

661

662−Associative list of [++term]() [`++twig`](), used in [jet]() hint processing.

662+Associative list of [`++term`]() [`++hoon`](), used in [jet]() hint processing.

663

664Source

665------

666

667− ++ tyre (list ,[p=term q=twig]) ::

667+ ++ tyre (list ,[p=term q=hoon]) ::

668

669

670

@@ -716,7 +716,7 @@ See also: [`++typo`](), [`++seer`]()

716Address in subject. A `++wing` is a path to a value in the subject. A

717term alone is the trivial case of a `++wing`.

718

719−See also: `++twig`

719+See also: `++hoon`

720

721 > (ream 'a.+.c')

722 [%cnzz p=~[%a [%.y p=3] %c]]

docs/hoon/rune/buc.md+1−1

@@ -22,7 +22,7 @@ x)))`, it's a normalizer and can be used as a mold.

22statically, so we can't actually tell if a mold matches this

23definition perfectly. This is not actually a problem.)

25−Twigs in the `$` family are macros designed for making molds.

25+Runes in the `$` family are macros designed for making molds.

26But any hoon may produce a mold. (This is why `model` is a

27synonym for `hoon`).

docs/hoon/rune/sig.md+1−1

@@ -7,7 +7,7 @@ title: Hint ~ ("sig")

8# Hint `~` ("sig")

10−Twigs that use Nock `10` to pass non-semantic info to the

10+Runes that use Nock `10` to pass non-semantic info to the

11interpreter.

13## Hoons

docs/hoon/rune/wut.md+4−4

@@ -6,7 +6,7 @@ title: Test ? ("wut")

6---

8# Test `?` ("wut")

9−

10Hoon has the usual branches and logical tests. For pattern

11matching, it also has a [`?=` ("wuttis")](./tis/) rune that tests whether a value

12matches the icon of a mold. And it has branch inference,

@@ -22,9 +22,9 @@ type for the branches of the `?:`. Branch inference also works

22for expressions which expand to `?:`.

24The test does not have to be a single `?=`; the compiler can

25−analyze arbitrary boolean logic ([`?&` ("wutpam")](./pam/),

25+analyze arbitrary boolean logic ([`?&` ("wutpam")](./pam/),

26−[`?|` ("wutbar")](./bar/), [`?!` ("wutzap")](./zap/)) with full

26+[`?|` ("wutbar")](./bar/), [`?!` ("wutzap")](./zap/)) with full

27−short-circuiting. Equality tests ([`.=` ("dottis")](../dot/tis/)) are *not*

27+short-circuiting. Equality tests ([`.=` ("dottis")](../dot/tis/)) are *not*

28analyzed.

30If the compiler detects that the branch is degenerate (only one

docs/hoon/syntax.md+62−62

@@ -7,8 +7,8 @@ title: Syntax

8# Hoon syntax

10−Hoon's syntax is unusual, and to beginners it can look a lot more

10+Hoon's syntax is unusual, and to beginners it can look a lot more

11−complex than it really is. However, we believe that anyone who

11+complex than it really is. However, we believe that anyone who

12learns Hoon syntax will find that it has a number of advantages.

14# Motivation

@@ -19,7 +19,7 @@ piles*, *indentation creep*, and *feature/label confusion*.

20## Terminator piles

22−*Terminator piles* are like Lisp's stacks of right parentheses.

22+*Terminator piles* are like Lisp's stacks of right parentheses.

23Significant whitespace solves this problem and creates others.

25Hoon has no terminator piles. Except for a 1-space / more-space

@@ -29,8 +29,8 @@ distinction, it has no significant whitespace.

30*Indentation creep* is a problem caused by indentation conventions

31where the indentation point is a function of expression tree

32−depth. This problem is especially irritating when working with

32+depth. This problem is especially irritating when working with

33−long functions. It's true that short functions are better, but

33+long functions. It's true that short functions are better, but

34long ones sometimes need to be written.

36A procedural block has a backbone of statements which flows

@@ -48,19 +48,19 @@ shaped more or less like procedural programs.

48## Feature/label confusion

50*Feature/label confusion* (FLC) is the result of any syntax that

51−makes it hard for the eye to tell whether a token on the screen is

51+makes it hard for the eye to tell whether a token on the screen is

52−a feature of the language, or a label in the program. For example,

52+a feature of the language, or a label in the program. For example,

53in Lisp a special form has the same syntax as a function call.

55The worst-case result of FLC is "DSL cancer." Every source file

56is effectively written in its own domain-specific language. To

57read a new file is to learn a new language—"write-only code."

59−User-level macros, operator overloading, even excessive use of

59+User-level macros, operator overloading, even excessive use of

60−higher-order programming, can all lead quickly to the tragedy of

60+higher-order programming, can all lead quickly to the tragedy of

61write-only code.

63−Hoon has no FLC, user-level macros, or overloading. It does

63+Hoon has no FLC, user-level macros, or overloading. It does

64support higher-order programming; write-only Hoon can certainly be

65(and has been) written. But good Hoon style is to avoid it.

@@ -71,12 +71,12 @@ regularities. We'll cover those here.

72## Glyphs and characters

74−Hoon source uses ASCII text. Hoon does not accept non-ASCII

74+Hoon source uses ASCII text. Hoon does not accept non-ASCII

75text in source files, except UTF-8 in quoted strings. Hard

76tab characters are illegal.

78−Hoon is a heavy punctuation user. Reading off code aloud

78+Hoon is a heavy punctuation user. Reading off code aloud

79−using the proper names of ASCII symbols is tedious, so we've

79+using the proper names of ASCII symbols is tedious, so we've

80mapped each punctuation glyph to a syllable:

82```

@@ -94,31 +94,31 @@ fas / pat @ wut ?

94zap !

95```

97−You don't need to memorize these glyph names, but it might help.

97+You don't need to memorize these glyph names, but it might help.

98Code is often vocalized or subvocalized. "pal" is easier to say,

99aloud or silently, than "left paren".

100

101Note that the list includes two separate whitespace forms: `ace`

102for a single space; `gap` is either 2+ spaces or a newline. In Hoon,

103the only significance in whitespace is the difference between

104−`ace` and `gap`. Comments also count as `gap` whitespace—they

104+`ace` and `gap`. Comments also count as `gap` whitespace—they

105start with `::` and run to the end of the line.

106

107−An 80-column right margin is strongly encouraged. Really

107+An 80-column right margin is strongly encouraged. Really

108−well-groomed Hoon uses a 55-column code margin and puts a standard

108+well-groomed Hoon uses a 55-column code margin and puts a standard

109line comment at column 57.

110

111## Expressions and Runes

112

113−Each regular Hoon expression begins with a

113+Each regular Hoon expression begins with a

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

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

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

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

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

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

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

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

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

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

119we say "colhep".

120

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

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

122kind of subexpressions depend on the rune used.

123

124```

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

1263

127```

128

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

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

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

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

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

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

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

133

134−Hoon expressions are just called

134+Hoon expressions are just called

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

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

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

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

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

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

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

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

140

141## Tall and flat forms

142

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

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

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

145contain flat hoons, but not vice versa.

146

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

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

148the flat equivalent:

149

150`:-(25 3)`

@@ -167,8 +167,8 @@ principles at all. All irregular forms are flat.

16723

168```

169

170−The `.=` rune tests for equality the two subexpressions that

170+The `.=` rune tests for equality the two subexpressions that

171−follow, and returns a boolean. Above is the tall, regular form of

171+follow, and returns a boolean. Above is the tall, regular form of

172`.=`. Below is the irregular form:

173

174`=(22 23)`

@@ -178,29 +178,29 @@ Some hoons have *only* irregular forms.

178## Tall regular form

179

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

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

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

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

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

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

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

184subexpressions by a `gap`.

185

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

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

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

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

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

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

189

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

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

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

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

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

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

194`--` (*battery*).

195

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

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

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

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

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

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

200and then a gap.

201

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

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

203−writing code with optimal whitespace management requires some

203+writing code with optimal whitespace management requires some

204additional informal conventions.

205

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

@@ -210,13 +210,13 @@ But it would at least take machine learning, not a rule engine.)

210

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

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

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

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

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

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

216

217### Conventions: *fixed*

218

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

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

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

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

222

@@ -239,13 +239,13 @@ r

239s

240```

241

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

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

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

244

245### Conventions: *running*

246

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

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

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

249down:

250

251A *running* example:

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

261

262### Conventions: *jogging*

263

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

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

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

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

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

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

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

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

268last fixed child.

269

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

@@ -297,8 +297,8 @@ A *tall jogging* example (preceded by *1-fixed* `p`):

297

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

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

300−of a

300+of a

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

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

302conventional example:

303

304```

@@ -314,7 +314,7 @@ conventional example:

314

315## Flat regular form

316

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

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

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

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

320parenthesis).

@@ -356,10 +356,10 @@ appropriate.

356

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

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

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

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

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

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

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

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

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

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

363four; five is stretching it; six is outright ridiculous.

364

365For example, when defining `add`, we want to name the operands