@@ -1,19 +1,21 @@
11+++
22title = "Hoon Syntax"
3−weight = 22
3+weight = 13
44template = "doc.html"
55+++
6+# 1.3 Hoon Syntax
7+
68The study of Hoon can be divided into two parts: syntax and semantics.
79
8−The [syntax](https://en.wikipedia.org/wiki/Syntax_%28programming_languages%29) of a programming language is the set of rules that determine what counts as admissible code in that language. It determines which characters may be used in the source, and also how these characters may be assembled to constitute a program. Attempting to run a program that doesn't follow these rules will result in a syntax error.
10+The [syntax](https://en.wikipedia.org/wiki/Syntax_(programming_languages%29) of a programming language is the set of rules that determine what counts as admissible code in that language. It determines which characters may be used in the source, and also how these characters may be assembled to constitute a program. Attempting to run a program that doesn't follow these rules will result in a syntax error.
911
10−The [semantics](https://en.wikipedia.org/wiki/Semantics_%28computer_science%29) of a programming language concerns the meaning of the various parts of that language's code.
12+The [semantics](https://en.wikipedia.org/wiki/Semantics_(computer_science%29) of a programming language concerns the meaning of the various parts of that language's code.
1113
12−In this lesson we cover Hoon's syntax. A strict account of Hoon's syntax would refrain from making any reference at all to semantics, but for ease of exposition we won't be quite so fastidious.
14+In this lesson we will give a general overview of Hoon's syntax. By the end of it, you should be familiar with all the basic elements of Hoon code.
1315
1416## Hoon Characters
1517
16−Hoon source files are composed almost entirely of the [printable ASCII characters](https://en.wikipedia.org/wiki/ASCII#Printable_characters). Hoon does not accept any other characters in source files except for [UTF-8](https://en.wikipedia.org/wiki/UTF-8) in quoted strings. Hard tab characters are illegal.
18+Hoon source files are composed almost entirely of the [printable ASCII characters](https://en.wikipedia.org/wiki/ASCII#Printable_characters). Hoon does not accept any other characters in source files except for [UTF-8](https://en.wikipedia.org/wiki/UTF-8) in quoted strings. Hard tab characters are illegal; use two spaces instead.
1719
1820```
1921> "You can put ½ in quotes, but not elsewhere!"
@@ -51,7 +53,7 @@ Note that the list includes two separate whitespace forms: `ace` for a single sp
5153
5254## Expressions of Hoon
5355
54−An [expression](https://en.wikipedia.org/wiki/Expression_%28computer_science%29) is a combination of characters that the language interprets and evaluates as producing a value. Hoon programs are made up entirely of expressions.
56+An [expression](https://en.wikipedia.org/wiki/Expression_(computer_science%29) is a combination of characters that the language interprets and evaluates as producing a value. Hoon programs are made up entirely of expressions.
5557
5658Hoon expressions can be either basic or complex. Basic expressions of Hoon are fundamental, meaning that they can't be broken down into smaller expressions. Complex expressions are made up of smaller expressions (which are called **subexpressions**).
5759
@@ -61,7 +63,7 @@ There are many categories of Hoon expressions: noun literals, wing expressions,
6163
6264A noun is either an atom or a cell. An atom is an unsigned integer and a cell is a pair of nouns.
6365
64−There are [literal](https://en.wikipedia.org/wiki/Literal_%28computer_programming%29) expressions for each kind of noun. A noun literal is just a notation for representing a fixed noun value.
66+There are [literal](https://en.wikipedia.org/wiki/Literal_(computer_programming%29) expressions for each kind of noun. A noun literal is just a notation for representing a fixed noun value.
6567
6668We start with atom literals. Each of these is a basic expression of Hoon that evaluates to itself. Examples:
6769
@@ -80,12 +82,6 @@ We start with atom literals. Each of these is a basic expression of Hoon that e
8082
8183> ~zod
8284~zod
83−
84−> 0xdead.beef
85−0xdead.beef
86−
87−> 0b1101.1001
88−0b1101.1001
8985```
9086
9187Recall from [lesson 1.2](../nouns) that even though atoms are unsigned integers, they can be pretty-printed in different ways. The way an atom is to be represented depends on its aura. The literal syntax for each of the hard-coded auras will be explained further in [lesson 2.4](../atoms-auras-and-simple-cell-types).
@@ -127,7 +123,6 @@ Let's start with the base case: a single limb. A limb expression is a trivial w
127123- `b`
128124- `add`
129125- `mul`
130−- `kebab-case-123`
131126
132127As a special limb we also have `$`. This is the name of the arm in special one-armed cores called "gates". (We covered the role of `$` in [lesson 1.5](../hoon-ch1-5).)
133128
@@ -141,6 +136,7 @@ Wing expressions with multiple limbs are complex expressions. Examples:
141136- `-.b.+2`
142137- `-.add`
143138
139+
144140### Type Expressions
145141
146142Hoon is a statically typed language. You'll learn more about the type system later in the chapter. For now, just know that Hoon's type system uses special symbols to indicate certain fundamental types: `~` (null), `*` (noun), `@` (atom), `^` (cell), and `?` (flag). Each of these symbols can be used as a stand-alone expression of Hoon. In the case of `@` there may be a series of letters following it, to indicate an atom aura; e.g., `@s`, `@rs`, `@tas`, and `@tD`.
@@ -202,13 +198,6 @@ Let's look at another example. The `.=` rune takes two subexpressions, evaluate
202198> .= 22 11
203199%.n
204200
205−> .= 22 (add 11 11)
206−%.y
207−
208−> .= 22
209− 11
210−%.n
211−
212201> .= 22
213202 (add 11 11)
214203%.y
@@ -257,51 +246,7 @@ The irregular `( )` gate-calling syntax is versatile -- it is also a shortcut fo
25724610
258247```
259248
260−The `( )` gate-calling syntax can be used for gates of any other [arity](https://en.wikipedia.org/wiki/Arity) as well.
261−
262−You've already seen two other irregular forms. In [lesson 1.5](../gates), you made a gate that takes an atom `a` for its sample and returns `a + 1`: `|=(a=@ (add 1 a))`. This expression uses the `|=` rune in flat form.
263−
264−```
265−> =inc |=(a=@ (add 1 a))
266−
267−> (inc 10)
268−11
269−
270−> (inc 15)
271−16
272−```
273−
274−The `a=@` subexpression -- used to define the face and the type of the gate's sample -- is the irregular form of `$=(a @)`:
275−
276−```
277−> =inc |=($=(a @) (add 1 a))
278−
279−> (inc 10)
280−11
281−
282−> (inc 15)
283−16
284−```
285−
286−In the previous chapter you also defined faces in nouns as in the following examples:
287−
288−```
289−> b:[a=15 b=25 c=35]
290−25
291−
292−> c:[a=15 b=25 c=35]
293−35
294−```
295−
296−The `a=15` expression is the irregular form of `^=(a 15)`:
297−
298−```
299−> b:[^=(a 15) ^=(b 25) ^=(c 35)]
300−25
301−
302−> c:[^=(a 15) ^=(b 25) ^=(c 35)]
303−35
304−```
249+The `( )` gate-calling syntax can be used for gates with any number of arguments.
305250
306251You can find other irregular forms in the irregular expression [reference document](/docs/reference/irregular).
307252
@@ -315,9 +260,6 @@ Below we use the `` ` `` symbol to create a cell whose head is null, `~`.
315260> `12
316261[~ 12]
317262
318−> `[12 14]
319−[~ 12 14]
320−
321263> `[[12 14] 16]
322264[~ [12 14] 16]
323265```
@@ -339,229 +281,46 @@ b=[16 18]
339281
340282> ,.+:[a=[12 14] b=[16 18]]
341283[16 18]
342−
343−> ,.+:[a=[12 14] [16 18]]
344−[16 18]
345284```
346285
347286To see other irregular expressions, check the irregular expression [reference document](docs/reference/irregular).
348287
349−## Hoon Style
350−
351−See [Hoon Style Guide](https://urbit.org/docs/learn/hoon/style/).
352−
353−### Rune Expression Body Types
354−
355−Let's call everything in the expression after the initial rune the expression **body**. There are four kinds of body: **fixed**, **running**, **jogging**, and **battery**. There is a preferred manner of styling for each body.
288+## The Standard Library
356289
357−#### Fixed
290+The Hoon standard library is a compilation of generally useful Hoon gates (functions). You've seen these already: in expressions like `(add 11 11)`, `add` is a function from the standard library.
358291
359−Some runes have a **fixed** number of subexpressions. For example, the `:-` and `.=` runes each have exactly two.
360−
361−Fixed bodies often use "backstep" indentation in tall form. In backstep indentation the code slopes backward and to the right by two spaces per line. The last subexpression isn't indented at all, and the first subexpression is on the same line as the rune. The indentation of the first subexpression therefore depends upon the total number of subexpressions.
362−
363−We'll use the `:` family of runes to illustrate. The `:-` rune creates a cell from two subexpressions, `:+` creates a cell from three, and `:^` creates a cell from four. In flat form:
292+It's important to know about standard library functions, because they make certain tasks much easier, and spare you from having to write the code itself. If you did not use the `add` library function, for example, you would have to write out code like this every time you wanted to find the sum of two numbers:
364293
365294```
366−> :-(11 22)
367−[11 22]
368−
369−> :+(11 22 33)
370−[11 22 33]
371−
372−> :^(11 22 33 44)
373−[11 22 33 44]
295+++ add
296+ ~/ %add
297+ |= [a=@ b=@]
298+ ^- @
299+ ?: =(0 a) b
300+ $(a (dec a), b +(b))
374301```
375302
376−Let's look at these in tall form, using backstep indentation:
303+Standard library functions are often built with other standard library functions, but ultimately those functions used are only built with runes. Notice how in the code above `add` is built with the `dec` function, which decrements a value by `1`.
377304
378−```
379−> :- 11
380− 22
381−[11 22]
382−
383−> :+ 11
384− 22
385− 33
386−[11 22 33]
387−
388−> :^ 11
389− 22
390− 33
391− 44
392−[11 22 33 44]
393−```
394−
395−
396−Some other **1-fixed**, **2-fixed**, **3-fixed** and **4-fixed** examples, using `p`, `q`, `r`, and `s` for the subexpressions:
397−
398−```
399−|.
400−p
401−
402−=| p
403−q
404−
405−?: p
406− q
407−r
408−
409−%^ p
410− q
411− r
412−s
413−```
305+## Reference Materials
414306
415−In optimal usage of backstep indentation the most complicated subexpressions are at the bottom. This helps keep code flow vertical rather than diagonal.
416−
417−#### Running
418−
419−A **running** body doesn't have a fixed number of subexpressions; expressions with running bodies can be arbitrarily long.
420−
421−To indicate the end of such expressions in tall form, use the `==` rune. The first subexpression is two spaces after the initial rune, and all others are indented to line up with the first. The terminating `==` should align vertically with the initial rune. In flat form, parentheses are used around the expression body, so the terminating `==` is unnecessary.
422−
423−The `:*` rune is used to create a cell of arbitrary length:
424−
425−```
426−> :*(11 22 33)
427−[11 22 33]
428−
429−> :*(11 22 33 44)
430−[11 22 33 44]
431−
432−> :*(11 22 33 44 55)
433−[11 22 33 44 55]
434−```
435−
436−We'll use `:*` to illustrate proper tall form running body style:
437−
438−```
439−> :* 11
440− 22
441− 33
442− 44
443− 55
444− ==
445−[11 22 33 44 55]
446−```
447−
448−More generally:
449−
450−```
451−:* p
452− q
453− r
454− s
455− t
456−==
457−```
458−
459−#### Jogging
460−
461−A **jogging** body is an arbitrarily long series of subexpression pairs. Most jogging bodies are preceded by a fixed sequence of subexpressions. The first jogging pair is one line after the last fixed subexpression, and indented two spaces behind it. There are two jogging conventions: **flat** (each pair on one line) and **tall** (each pair split across lines). In either case the expression is terminated with a `==`.
462−
463−The `?-` rune is `1-fixed` followed by a jogging body. The fixed subexpression is evaluated and then compared against the left subexpression of each of the jogging pairs. When a match is found, the subexpression to the right of the match is evaluated.
464−
465−For example:
466−
467−```
468−> ?- `?(%2 %3 %4)`%2
469− %2 %yes
470− %3 %no
471− %4 %no
472− ==
473−%yes
474−```
475−
476−More generally, the **flat jogging** style (preceded by **1-fixed** `p`):
477−
478−```
479−?- p
480− q r
481− s t
482− u v
483−==
484−```
485−
486−A **tall jogging** example (preceded by **1-fixed** `p`):
487−
488−```
489−?- p
490− q
491− r
492− s
493− t
494− u
495− v
496−==
497−```
498−
499−In flat form for **jogging** bodies, subexpression pairs are separated by commas:
500−
501−```
502−$(a +(a), b (dec b), c (add 2 c))
503−```
504−
505−#### Battery
506−
507−Certain runes are used to create a core. Cores with multiple arms have a special syntax for defining each of the arms in the battery. A core has no fixed limit on the number of arms contained in its battery, so you must terminate core expressions with the `--` rune. Each arm in the battery is defined with three things: (1) a rune in the `+` family (e.g., `++`, `+*`, and `+$`), (2) an arm name, and (3) a subexpression defining the content of that arm. Runes in the `+` family may only go in core subexpressions. Putting them anywhere else results in a syntax error.
508−
509−Here's an example of a **battery** body:
510−
511−```
512−|%
513−++ arm-1
514− %p
515−++ arm-2
516− %q
517−++ arm-3
518− %r
519−--
520−```
521−
522−## Motivation
523−
524−There's no denying that Hoon's syntax is a bit strange, especially for those used to working in other programming languages. Hoon makes heavy use of ASCII characters, and this can be intimidating to newcomers. However, we believe that anyone who learns Hoon syntax will find that it has a number of advantages.
525−
526−Hoon's syntax is designed to address three serious problems in functional syntax design. These problems are: (1) **terminator piles**, (2) **indentation creep**, and (3) **feature/label confusion**.
527−
528−### Terminator piles
529−
530−A **terminator pile** is a series of termination characters required to end some expression in a language. Think of Lisp's stacks of right parentheses. For a trivial example, let's say you want to add 22 five times in Lisp using `+`:
531−
532−```
533−(+ 22 (+ 22 (+ 22 (+ 22 22))))
534−```
535−
536−In a sufficiently complicated expression it's tedious to keep track of all the parentheses in the terminator pile. You can write terminator piles in Hoon code if you really want to:
537−
538−```
539−> (add 22 (add 22 (add 22 (add 22 22))))
540−110
541−```
542−
543−...but you are never forced to do so. There is always a semantically equivalent alternative syntax without them:
544−
545−```
546−> %+ add 22
547− %+ add 22
548− %+ add 22
549− %+ add 22 22
550−110
551−```
307+The Hoon syntax can be intimidating for the uninitiated, so it's good to remember where you can look up expressions can be found. The [reference section](/docs/reference/) itself is a good place to find the reference materials that you need. These children sections are likely to be useful:
552308
553−### Indentation creep
309+- The [Runes](/docs/reference/hoon-expressions/) page will show you how to use any Hoon rune.
310+- The [Cheat sheet](/docs/reference/cheat-sheet/) is a more compact place to look up rune expressions.
311+- The [Standard library](/docs/reference/library/) section has its sub-pages arranged by category. So arithmetic functions, for example, are all found on the same page.
312+- The [Hoon Style Guide](/docs/learn/hoon/style/) will show you how to write your Hoon code so that it's idiomatic and easily understood by others.
554313
555−In some programming languages there is an indentation convention according to which an expression embedded within a parent expression is indented more to the right. In a sufficiently long and complicated function with many embedded subexpressions, the tendency is for the code to shift more and more to the right. This tendency is called **indentation creep**, and it can become an irritating problem when working with long functions. It's true that short functions are better, but long ones sometimes need to be written.
314+### Debugging
556315
557−Ordinary indentation conventions give long functions a _diagonal_ shape, which is a poor fit for most editor windows. Because Hoon is designed to be written with 'backstep' indentation, the code flows _down_, not down and across.
316+When you have an error in your Hoon code, one of two things can happen. Either the code does not run at all and you get an error (such as `nest-fail`), or your code _does_ run but produces the wrong results. The [Troubleshooting](/docs/reference/troubleshooting/) page is a good resource for figuring out how to debug your code.
558317
559−### Feature/label confusion
318+There are a couple useful runes associated with debugging:
560319
561−A language lends itself to **feature/label confusion** (FLC) when it's difficult to distinguish general features of the language from labels in a particular program. This can be a serious problem other functional programming languages. In Lisp, for example, a user-defined macro has the same syntax as a function call.
320+`!:` (zapcol), if written at the top of a Hoon file, turns on a full debugging stack-trace. It's good practice to use whenever you're learning.
562321
563−The worst-case result of FLC is "DSL cancer". Every source file with this malady is effectively written in its own domain-specific language (DSL). Learning to read such a file is like learning a language. One can also describe the result as "write-only code". User-level macros, operator overloading, and even excessive use of higher-order programming, can all lead quickly to the tragedy of write-only code.
322+`~&` (sigpam) is used to print its argument every time that argument executes. So, if you wanted to see how many times your program executed `foo`, you would write `foo bar`. Then, when your program runs, it will print `foo` on a new line of output every time the program comes across it by recursion.
564323
565−Hoon largely avoids FLC by its use of runes. Hoon has no user-level macros or operator overloading. It does support higher-order programming; write-only Hoon can certainly be (and has been) written. However, with a little discipline one can write Hoon without inventing a DSL.
324+But there are more. Check out the aforementioned [troubleshooting](/docs/reference/troubleshooting/) page to see other handy debugging runes and how to use them.
566325
567−### [Next Lesson: Simple One-Gate Programs](../simple-one-gate-programs)
326+### [Next Lesson: The Subject and Its Legs](../the-subect-and-its-legs)