@@ -1,297 +0,0 @@
3−Because each twig stem has its own bulb, each has its own parser
4−rule. We'll describe these grammars as we go through the stems.
6−But Hoon has a general syntax design with common principles and
7−regularities. We'll cover those here.
9−## Glyphs and characters
11−Hoon is a heavy punctuation user. To make ASCII great again,
12−we've mapped each punctuation glyph to a syllable:
15− ace [1 space] gal < pal (
16− bar | gap [>1 space, nl] par )
29−You don't need to memorize these glyph names, but it helps. Code
30−is often vocalized or subvocalized. "pal" is easier to say,
31−aloud or silently, then "left paren."
33−Note that the list includes two separate whitespace forms: `ace`
34−for a single space, `gap` for 2+, comment or newline. Hoon
35−Besides `ace` versus `gap`, whitespace is not significant.
37−Comments start with `::` and run to the end of the line. Hard
38−tab characters are illegal, and an 80-column right margin is
39−strongly encouraged. Really well-groomed Hoon uses a 55-column
40−code margin and puts a standard line comment at column 57.
42−Hoon does not accept non-ASCII text in source files, except UTF-8
45−## Tall and flat forms
47−There are two kinds of Hoon expression syntax: *tall* and *flat*.
48−Most stems have both tall and flat forms. Tall twigs can contain
49−flat twigs, but not vice versa.
51−Visually, a tall twig looks like a "statement" and a flat twig
52−like an "expression," preserving the attractive visual shape of
53−procedural code without the nasty side effects.
55−## Regular and irregular forms
57−Most stems have *regular forms*, which share a common design.
58−There is a regular flat form and a regular tall form; most stems
59−implement both. All tall forms are regular.
61−Some twigs also have *irregular forms*, which follow no
62−principles at all. All irregular forms are flat.
64−Some twigs (simple leafy ones) have *only* irregular forms.
66−## Keywords versus runes
68−A regular form starts with a *sigil*, which is either a
69−*keyword* or a *rune* -- at the programmer's choice.
71−A *keyword* is `:` and then the stem label - eg, `:cons`.
73−A *rune* is a pair of ASCII punctuation marks (a digraph) - eg,
74−`:-`. The first glyph in the rune indicates the category - eg,
75−`:` runes make cells. Runes can be pronounced by their glyphs or
76−by their stem -- for `:-`, you can say either "colhep" or "cons".
78−Keywords may be less challenging for early learners. Rune style
79−is less cluttered and distracting for experienced programmers;
80−the system codebase is all in rune style. Beginners can start
81−with keywords and move to runes; start with runes and stick
82−with runes; or start with keywords and stick with keywords.
84−Here's the FizzBuzz demo code, in idiomatic rune syntax. Compare
85−with the [original](../../demo).
92− :_ $(count (add 1 count))
93− ?: =(0 (mod count 15))
95− ?: =(0 (mod count 5))
97− ?: =(0 (mod count 3))
104−Tall regular form starts with the sigil, followed by a `gap`
105−(any whitespace except `ace`), followed by a bulb whose twigs are
108−There are four body subtypes: *fixed*, *running*, *jogging*, and
109−*battery*. Stems with a *fixed* number of subexpressions
110−self-terminate. For instance, `:if` has three subexpressions and
111−is self-terminating. Otherwise the twig is terminated by a
112−`gap`, then either `==` (*running* or *jogging*, most twigs) or
115−The *running* body is a list of twigs. The *jogging* body is a
116−list of twig pairs, separated by a `gap`. The *battery* body is
117−a list of symbol-twig pairs, separated by a gap, prefixed by `++`
120−This definition is enough to parse. But the proper shape of the
121−whitespace gaps demands an informal convention.
123−Whitespace design in Hoon is an art, not a science. It involves
124−both tall/flat mode switches and well-shaped gaps. (Hoon layout
125−could probably be done automatically with reasonable quality.
126−But it would at least take machine learning, not a rule engine.)
128−There only two real *rules* in Hoon whitespace design: don't
129−go past 80 characters, and don't use (completely) blank lines.
130−Otherwise, if it looks good and is easy to read, it's good. But
131−the best way to learn the art is to do everything by convention
132−until you know what you're doing. Here are the conventions:
134−### Conventions: *fixed*
136−Bulbs with *fixed* fanout use "backstep" indentation, which slopes
137−backward and to the right by two spaces per line. The first
138−child is two spaces after the end of the sigil.
140−Some *1-fixed*, *2-fixed*, *3-fixed* and *4-fixed* examples:
159−The hope of backstep indentation is that the heaviest twigs are
160−at the bottom, keeping code flow vertical rather than diagonal.
163−### Conventions: *running*
165−A *running* bulb (a simple child list) puts the first child two
166−spaces after the end of the sigil, and the following children
180−### Conventions: *jogging*
182−A *jogging* bulb (a list of child pairs) is like a running bulb,
183−but backsteps the head of the pair above the tail. Most jogging
184−twigs start with a *fixed* sequence; the first jogging pair is
185−below and two steps backward from the last fixed child.
187−There are two jogging conventions: *flat* (pair on one line) and
188−*tall* (pair split across lines).
190−A *flat jogging* example (preceded by *1-fixed* `p`)
200−A *tall jogging* example (preceded by *1-fixed* `p`):
213−### Conventions: *battery*
215−A *battery* bulb is a list of symbol-twig pairs, for the battery
216−of a core. A conventional example:
229−Flat regular form starts with the sigil, followed by `pal`
230−(`(`, left parenthesis), followed by a bulb whose subexpressions
231−are separated by `ace` (one space), followed by `par` (`)`, right
234−A twig in flat form, `:if`, `?:`, `{$if p/twig q/twig r/twig}`:
242−The only exception is *jogging* bodies, in which subexpression
243−pairs are separated by commas:
246−:make(foo bar 42, baz 55, moo 17)
249−There is no flat regular form for *battery* bodies. Be tall.
251−## Naming conventions
253−Hoon does not enforce any rule on symbols, except that capitals
254−are not allowed (use kebab-case). However, a lot of system code
255−is written in using "lapidary" conventions that need explanation.
257−Naming things is one of the hard problems in CS. Dodging this
258−problem is one of the reasons mathematicians use Greek letters,
259−not variable names. Meaningful names also interpose a verbal
260−interpretation, distracting at best and confusing at worst, on
261−the formula or algorithm. Greek letters are not *meaningful*,
262−but they are *memorable*. And their interpretation is defined by
263−the formula and nothing else.
265−### Lapidary and ultralapidary
267−In the *lapidary* naming style, labels are pronounceable
268−three-letter strings, usually CVC (consonant-vowel-consonant).
269−Sometimes they encode a mnemonic, but usually they are just
270−memorable. Labels are reused wherever the analogy seems
273−In the *ultralapidary* naming style, labels are single letters,
274−starting in order of construction from `a`, or within a tuple
275−mold `p`. Hoon uses single-letter names for the same reason
276−Algol style languages pass arguments by order, rather than
277−keyword. Naming items by order makes sense when there are no
278−more than three or four; five is stretching it; six is too many.
280−For example, when defining `add`, we want to name the operands
281−`a` and `b`. It's silly to call them `foo` and `bar`, let alone
282−`left-operand` and `right-operand`. The smaller the scale of an
283−algorithm, the simpler its names should be.
285−### When in doubt, don't be lapidary
287−This works in the other direction: namelessness doesn't scale.
288−Most normal code shouldn't use lapidary naming at all. (Everyone
289−agrees: there is *way* too much lapidary Hoon in Urbit.)
291−Lapidary naming is only for *inherently simple code*: code that
292−both aspires to high elegance and clarity, and *is solving a
293−simple and elegant problem*.
295−Given an ugly or complex problem, lapidary naming is a liability,
296−no matter the excellence of the programmer. When in doubt, use
297−long names and/or kebab-case.