@@ -119,37 +119,42 @@ pairs). We pronounce runes using their glyph names—for `:-`,
119we say "colhep".
119we say "colhep".
121Each rune is followed by one or more subexpressions. The number and
121Each rune is followed by one or more subexpressions. The number and
122−kind of subexpressions depend on the rune used.
122+kind of subexpressions depend on which rune is used.
129−This twig uses `:-` to produce a cell: `[25 3]`. There are always two
129+The `:-` rune is always followed by two 'value' subexpressions to
130−subexpressions following the `:-` in syntactically correct Hoon code,
130+produce a cell: `[25 3]`. The first subexpression, when evaluated,
131−the first of which, when evaluated, becomes the *head* (i.e., the left)
131+becomes the *head* (i.e., the left) of the cell, and the second
132−and the second of which becomes the *tail* (i.e., the right).
132+becomes the *tail* (i.e., the right).
134−Hoon expressions are sometimes called
134+There are two kinds of expressions in Hoon: *value* and *pattern*.
135−[twigs](https://urbit.org/docs/about/glossary#twig). You'll find that
135+Value expressions evaluate to any sort of data. They can be as simple
136−Hoon code has a tree-like structure, so you can think of the various
136+as `25`, or they may require more computation, as in `(add 22 3)`. The
137−expressions as twigs of the tree. The subexpressions following the
137+`:-` expression above is itself a value expression, as are the vast
138−rune are sometimes called the *children* of that twig.
138+majority of Hoon expressions.
140−## Tall and flat forms
140+A pattern expression must be a *mold*, which we'll explain a bit
141+[later](https://urbit.org/docs/hoon/basic).
142−There are two kinds of Hoon expression syntax: *tall* and *flat*.
143+## Tall and flat styles
143−Most runes can be used in both tall and flat twigs. Tall twigs can
144−contain flat twigs, but not vice versa.
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
146−The `:-` expression in the last subsection was in tall form. Here's
151+The `:-` expression in the last subsection was in tall style. Here's
147the flat equivalent:
152the flat equivalent:
149`:-(25 3)`
154`:-(25 3)`
151−Visually, a tall twig looks like a "statement" and a flat twig
156+Visually, the tall style looks more "statement"-like and flat-style
152−like an "expression," preserving the attractive visual shape of
157+looks "expression"-like, preserving the attractive visual shape of
153procedural code without the nasty side effects.
158procedural code without the nasty side effects.
155## Regular and irregular forms
160## Regular and irregular forms
@@ -159,7 +164,7 @@ There is a regular flat form and a regular tall form; most runes
159have both kinds of implementation. All tall forms are regular.
164have both kinds of implementation. All tall forms are regular.
161Some runes also have *irregular forms*, which follow no
166Some runes also have *irregular forms*, which follow no
162−principles at all. All irregular forms are flat.
167+general principles at all. All irregular forms are flat.
@@ -172,52 +177,51 @@ follow, and returns a boolean. Above is the tall, regular form of
173`=(22 23)`
178`=(22 23)`
175−Some twigs have *only* irregular forms.
180+Some kinds of expression have *only* irregular forms.
177## Tall regular form
182## Tall regular form
179Tall regular forms start with a rune followed by a `gap`.
184Tall regular forms start with a rune followed by a `gap`.
180−(Remember, a `gap` is any whitespace other than `ace`.) After
185+(Remember, a `gap` is any whitespace other than `ace`, or a line
181−that are the number and types of subexpressions appropriate for
186+break.) After that are the number and types of subexpressions
182−that rune. Each subexpression is separated from its neighboring
187+appropriate for that rune. Each subexpression is separated from
183−subexpressions by a `gap`.
188+its neighboring subexpressions by a `gap`.
185−Let's call everything in the twig after the initial rune the twig
190+Everything after the initial rune in an expression is called the
186−*body*. There are four body subtypes: *fixed*, *running*, *jogging*,
191+*body*. There are four body types: *fixed*, *running*, *jogging*,
187and *[battery](https://urbit.org/docs/about/glossary#battery)*.
192and *[battery](https://urbit.org/docs/about/glossary#battery)*.
189Runes with a *fixed* number of subexpressions self-terminate. For
194Runes with a *fixed* number of subexpressions self-terminate. For
190instance, the `:-` and `.=` runes each have two subexpressions
195instance, the `:-` and `.=` runes each have two subexpressions
191−and are self-terminating. Otherwise the twig is terminated by both
196+and are self-terminating. Otherwise the body is terminated by a
192−a `gap`, then either `==` (*running* or *jogging*, most twigs) or
197+`gap` followed by either `==` (*running* or *jogging*, most runes)
193−`--` (*battery*).
198+or `--` (*battery*).
195−The *running* body has a list of *children* (i.e., subexpressions).
200+The *running* body is a list of *children* (i.e., subexpressions).
196−The *jogging* body has a list of child pairs, where the members of
201+The *jogging* body is a list of child pairs, where the members of
197each pair are separated by a `gap`. The *battery* body is
202each pair are separated by a `gap`. The *battery* body is
198−a list of symbol-child pairs, separated by a gap, prefixed by `++`
203+a list of symbol-child pairs, each separated by a `gap`. See below
199−and then a gap.
204+for examples of each body type.
201This definition is enough to write Hoon that will parse. But
206This definition is enough to write Hoon that will parse. But
202writing code with optimal whitespace management requires some
207writing code with optimal whitespace management requires some
203additional informal conventions.
208additional informal conventions.
205Whitespace design in Hoon is an art, not a science. It involves
210Whitespace design in Hoon is an art, not a science. It involves
206−both tall/flat mode switches and well-shaped gaps. (Hoon layout
211+both tall/flat style switches and well-shaped gaps. (Hoon layout
207could probably be done automatically with reasonable quality.
212could probably be done automatically with reasonable quality.
208But it would at least take machine learning, not a rule engine.)
213But it would at least take machine learning, not a rule engine.)
210There are only two real *rules* in Hoon whitespace design: don't
215There are only two real *rules* in Hoon whitespace design: don't
211go past 80 characters, and don't use (completely) blank lines.
216go past 80 characters, and don't use (completely) blank lines.
212−Otherwise, if it looks good and is easy to read, it's good. The
217+Otherwise, if it looks good and is easy to read, it's fine. The
213best way to learn the art is to do everything by convention
218best way to learn the art is to do everything by convention
214until you know what you're doing. Here are the conventions:
219until you know what you're doing. Here are the conventions:
216### Conventions: *fixed*
221### Conventions: *fixed*
218−Twig bodies with *fixed* fanout use "backstep" indentation, which
223+Expressions with *fixed* bodies use "backstep" indentation, which
219−slopes backward and to the right by two spaces per line. The first
224+slopes backward and to the right by two spaces per line.
220−twig child is two spaces after the end of the rune.
222Some *1-fixed*, *2-fixed*, *3-fixed* and *4-fixed* examples:
226Some *1-fixed*, *2-fixed*, *3-fixed* and *4-fixed* examples:
@@ -238,14 +242,15 @@ r
241−In optimal usage of backstep indentation, the most complicated twigs
245+In optimal usage of backstep indentation, the most complicated
242−are at the bottom, keeping code flow vertical rather than diagonal.
246+expressions are at the bottom, keeping code flow vertical rather than
244### Conventions: *running*
249### Conventions: *running*
246−A *running* twig body (a simple child list) puts the first child two
251+A *running* body (a simple child list of arbitrary length) puts the
247−spaces after the end of the rune, and the following children straight
252+first child two spaces after the end of the rune, and the following
248−down:
253+children straight down:
250A *running* example:
255A *running* example:
@@ -260,10 +265,10 @@ A *running* example:
261### Conventions: *jogging*
266### Conventions: *jogging*
263−A *jogging* twig body (a list of child pairs) is like a running
268+A *jogging* body (a list of child pairs of arbitrary length) is like
264−body, but with a pair of children on each line, separated by
269+a running body, but with a pair of children on each line separated by
265two spaces. Most jogging bodies start with a *fixed* sequence;
270two spaces. Most jogging bodies start with a *fixed* sequence;
266−the first jogging pair is below and two steps backward from the
271+the first pair is below and two steps backward from the
267last fixed child.
272last fixed child.
269There are two jogging conventions: *flat* (pair on one line) and
274There are two jogging conventions: *flat* (pair on one line) and
@@ -315,10 +320,10 @@ conventional example:
316Flat regular form starts with the rune, followed by `pal`, `(`
321Flat regular form starts with the rune, followed by `pal`, `(`
317(left parenthesis), followed by a body whose subexpressions
322(left parenthesis), followed by a body whose subexpressions
318−are separated by `ace` (one space), followed by `par`, `)` (right
323+are all separated by `ace`s (single spaces), followed by `par`,
319−parenthesis).
324+`)` (right parenthesis).
321−A twig in flat form, `:if`, `?:`, `{$if p/twig q/twig r/twig}`:
326+A expression in flat form, `?:`, which is 3-fixed:
323`?:(p q r)`
328`?:(p q r)`