git.iko.soy/urbit.org
on master help sign in
explaining Urbit terms upon first use
e665115Joshua Reagan
docs/hoon/syntax.md+26−14
compare with master
unifiedsplit
@@ -56,7 +56,7 @@ special form has the same syntax as a function call.
56
56
57The worst-case result of FLC is "DSL cancer." Every source file
57The worst-case result of FLC is "DSL cancer." Every source file
58is effectively written in its own domain-specific language. To
58is effectively written in its own domain-specific language. To
59−read a new file is to learn a new language -- "write-only code."
59+read a new file is to learn a new language—"write-only code."
60
60
61A fixed reserved-word set, especially with syntax highlighting,
61A fixed reserved-word set, especially with syntax highlighting,
62and especially with orthogonal grammar (in C, you don't write
62and especially with orthogonal grammar (in C, you don't write
@@ -71,15 +71,19 @@ higher-order programming; write-only Hoon can certainly be
71
71
72# Design
72# Design
73
73
74+Hoon expressions are called
75+*[twigs](https://urbit.org/docs/about/glossary#twig)*. The name
76+of a twig is its
77+*[stem](https://urbit.org/docs/about/glossary#stem)*. Because
74−Because each twig stem has its own bulb, each has its own parser
78+each twig stem has its own structure, each has its own parser
75−rule. We'll describe these grammars as we go through the stems.
79+rule. We'll describe these grammars as we go through the stems.
76
80
77But Hoon has a general syntax design with common principles and
81But Hoon has a general syntax design with common principles and
78regularities. We'll cover those here.
82regularities. We'll cover those here.
79
83
80## Glyphs and characters
84## Glyphs and characters
81
85
82−Hoon is a heavy punctuation user. To make ASCII great again,
86+Hoon is a heavy punctuation user. To aid pronunciation,
83we've mapped each punctuation glyph to a syllable:
87we've mapped each punctuation glyph to a syllable:
84
88
85```
89```
@@ -133,17 +137,20 @@ implement both. All tall forms are regular.
133Some twigs also have *irregular forms*, which follow no
137Some twigs also have *irregular forms*, which follow no
134principles at all. All irregular forms are flat.
138principles at all. All irregular forms are flat.
135
139
136−Some twigs (simple leafy ones) have *only* irregular forms.
140+Some twigs have *only* irregular forms.
137
141
138## Keywords versus runes
142## Keywords versus runes
139
143
140−A regular form starts with a *sigil*, which is either a
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
141−*keyword* or a *rune* -- at the programmer's choice.
148+the programmer's choice.
142
149
143−A *keyword* is `:` and then the stem label - e.g., `:cons`.
150+A *keyword* is `:` and then the stem label—e.g., `:cons`.
144
151
145−A *rune* is a pair of ASCII punctuation marks (a digraph) - e.g.,
152+A *rune* is a pair of ASCII punctuation marks (a digraph)—e.g.,
146−`:-`. The first glyph in the rune indicates the category - e.g.,
153+`:-`. The first glyph in the rune indicates the category—e.g.,
147`:` runes make cells. Runes can be pronounced by their glyphs or
154`:` runes make cells. Runes can be pronounced by their glyphs or
148by their stem -- for `:-`, you can say either "colhep" or "cons".
155by their stem -- for `:-`, you can say either "colhep" or "cons".
149
156
@@ -174,8 +181,10 @@ with the [original](../demo).
174## Tall regular form
181## Tall regular form
175
182
176Tall regular form starts with the sigil, followed by a `gap`
183Tall regular form starts with the sigil, followed by a `gap`
177−(any whitespace except `ace`), followed by a bulb whose twigs are
184+(any whitespace except `ace`). After this is a
178−separated by `gap`.
185+*[bulb](https://urbit.org/docs/about/glossary#bulb)*—the
186+contents of the twig—whose own twigs are separated by
187+`gap`.
179
188
180There are four body subtypes: *fixed*, *running*, *jogging*, and
189There are four body subtypes: *fixed*, *running*, *jogging*, and
181*battery*. Stems with a *fixed* number of subexpressions
190*battery*. Stems with a *fixed* number of subexpressions
@@ -284,8 +293,11 @@ A *tall jogging* example (preceded by *1-fixed* `p`):
284
293
285### Conventions: *battery*
294### Conventions: *battery*
286
295
287−A *battery* bulb is a list of symbol-twig pairs, for the battery
296+A *battery* bulb is a list of symbol-twig pairs, for the
297+*[battery](https://urbit.org/docs/about/glossary#battery)*
298+of a
299+*[core](https://urbit.org/docs/about/glossary#core)*. A
288−of a core. A conventional example:
300+conventional example:
289
301
290```
302```
291|%
303|%