@@ -72,13 +72,22 @@ higher-order programming; write-only Hoon can certainly be
74Hoon expressions are called
74Hoon expressions are called
75−*[twigs](https://urbit.org/docs/about/glossary#twig)*. The name
75+*[twigs](https://urbit.org/docs/about/glossary#twig)*, and at the
76−of a twig is its
76+beginning of each twig is a
77+*[rune](https://urbit.org/docs/about/glossary#rune)*. Each rune
78+type has a name, called a
77−*[stem](https://urbit.org/docs/about/glossary#stem)*. Because
79+*[stem](https://urbit.org/docs/about/glossary#stem)*. Finally,
78−each twig stem has its own structure, each has its own parser
80+each stem has its own structure, e.g.:
79−rule. We'll describe these grammars as we go through the stems.
81+
86+This twig uses the rune `:-` (stem: `cons`) to produce an ordered
87+pair: `[25 3]`. There are two subexpressions following the `:-`,
88+corresponding to the two parts of the `cons` structure.
81−But Hoon has a general syntax design with common principles and
90+Hoon has a general syntax design with common principles and
82regularities. We'll cover those here.
91regularities. We'll cover those here.
84## Glyphs and characters
93## Glyphs and characters
@@ -139,48 +148,19 @@ principles at all. All irregular forms are flat.
140Some twigs have *only* irregular forms.
149Some twigs have *only* irregular forms.
142−## Keywords versus runes
151+## Runes
144−A regular form starts with a
145−*[sigil](https://urbit.org/docs/about/glossary#sigil)*, which is
146−either a *keyword* or a
147−*[rune](https://urbit.org/docs/about/glossary#rune)*—at
148−the programmer's choice.
150−A *keyword* is `:` and then the stem label—e.g., `:cons`.
153+As mentioned earlier, a regular form starts with a
154+*[rune](https://urbit.org/docs/about/glossary#rune).
152A *rune* is a pair of ASCII punctuation marks (a digraph)—e.g.,
156A *rune* is a pair of ASCII punctuation marks (a digraph)—e.g.,
153`:-`. The first glyph in the rune indicates the category—e.g.,
157`:-`. The first glyph in the rune indicates the category—e.g.,
154`:` runes make cells. Runes can be pronounced by their glyphs or
158`:` runes make cells. Runes can be pronounced by their glyphs or
155−by their stem -- for `:-`, you can say either "colhep" or "cons".
159+by their stem—for `:-`, you can say either "colhep" or "cons".
157−Keywords may be less challenging for early learners. Rune style
158−is less cluttered and distracting for experienced programmers;
159−the system codebase is all in rune style. Beginners can start
160−with keywords and move to runes; start with runes and stick
161−with runes; or start with keywords and stick with keywords.
163−Here's the FizzBuzz demo code, in idiomatic rune syntax. Compare
164−with the [original](../demo).
171− :_ $(count (add 1 count))
172− ?: =(0 (mod count 15))
174− ?: =(0 (mod count 5))
176− ?: =(0 (mod count 3))
181## Tall regular form
161## Tall regular form
183−Tall regular form starts with the sigil, followed by a `gap`
163+Tall regular form starts with the rune, followed by a `gap`
184(any whitespace except `ace`). After this is a
164(any whitespace except `ace`). After this is a
185*[bulb](https://urbit.org/docs/about/glossary#bulb)*—the
165*[bulb](https://urbit.org/docs/about/glossary#bulb)*—the
186contents of the twig—whose own twigs are separated by
166contents of the twig—whose own twigs are separated by
@@ -188,7 +168,7 @@ contents of the twig—whose own twigs are separated by
189There are four body subtypes: *fixed*, *running*, *jogging*, and
169There are four body subtypes: *fixed*, *running*, *jogging*, and
190*battery*. Stems with a *fixed* number of subexpressions
170*battery*. Stems with a *fixed* number of subexpressions
191−self-terminate. For instance, `:if` has three subexpressions and
171+self-terminate. For instance, `?:` has three subexpressions and
192is self-terminating. Otherwise the twig is terminated by a
172is self-terminating. Otherwise the twig is terminated by a
193`gap`, then either `==` (*running* or *jogging*, most twigs) or
173`gap`, then either `==` (*running* or *jogging*, most twigs) or
194`--` (*battery*).
174`--` (*battery*).
@@ -312,7 +292,7 @@ conventional example:
313## Flat regular form
293## Flat regular form
315−Flat regular form starts with the sigil, followed by `pal`
295+Flat regular form starts with the rune, followed by `pal`
316(`(`, left parenthesis), followed by a bulb whose subexpressions
296(`(`, left parenthesis), followed by a bulb whose subexpressions
317are separated by `ace` (one space), followed by `par` (`)`, right
297are separated by `ace` (one space), followed by `par` (`)`, right
318parenthesis).
298parenthesis).