5e6a713 · urbit.org · git.iko.soy

47

48## Feature/label confusion

49

50−*Feature/label confusion* (FLC) is any syntax which makes it hard

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

51−for the eye to tell whether a token on the screen is a feature of

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

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

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

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

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

54

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

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

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 start with `::` and run to the end of

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

105−the line.

106

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

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

119we say "colhep".

120

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

122−kind of subexpressions depend on the rune.

122+kind of subexpressions depend on the rune used.

123

124```

125:- 25

134Hoon expressions are sometimes called

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

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

137−expressions as twigs of this tree. The subexpressions following the

137+expressions as twigs of the tree. The subexpressions following the

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

139

140## Tall and flat forms

176

177## Tall regular form

178

179−Tall regular form starts with the rune, followed by a `gap`.

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

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

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

181that are the number and types of subexpressions appropriate for

182−that rune. Each subexpression is separated from the others by a

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

183−`gap`.

183+subexpressions by a `gap`.

184

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

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

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

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

188

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

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

194

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

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

197−each pair is separated by a `gap`. The *battery* body is

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

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

199and then a gap.

200

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

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

202−proper shape of the whitespace gaps requires an informal convention.

202+writing code with optimal whitespace management requires some

203+additional informal conventions.

203

204

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

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

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

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

334

335

335Hoon does not enforce any rule on symbols, except that capitals

336Hoon does not enforce any rule on symbols, except that capitals

336are not allowed (use kebab-case). However, a lot of system code

337are not allowed (use kebab-case). However, a lot of system code

337−is written in using "lapidary" conventions that need explanation.

338+is written using "lapidary" conventions that need explanation.

338

339

339Naming things is one of the hard problems in CS. Dodging this

340Naming things is one of the hard problems in CS. Dodging this

340problem is one of the reasons mathematicians use Greek letters,

341problem is one of the reasons mathematicians use Greek letters,