@@ -14,7 +14,7 @@ The [syntax](https://en.wikipedia.org/wiki/Syntax_(programming_languages%29) of
1414
1515The [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.
1616
17−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.
17+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.
1818
1919## Hoon Characters
2020
@@ -85,12 +85,6 @@ We start with atom literals. Each of these is a basic expression of Hoon that e
8585
8686> ~zod
8787~zod
88−
89−> 0xdead.beef
90−0xdead.beef
91−
92−> 0b1101.1001
93−0b1101.1001
9488```
9589
9690Recall 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).
@@ -132,7 +126,6 @@ Let's start with the base case: a single limb. A limb expression is a trivial w
132126- `b`
133127- `add`
134128- `mul`
135−- `kebab-case-123`
136129
137130As 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).)
138131
@@ -146,6 +139,7 @@ Wing expressions with multiple limbs are complex expressions. Examples:
146139- `-.b.+2`
147140- `-.add`
148141
142+
149143### Type Expressions
150144
151145Hoon 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`.
@@ -207,13 +201,6 @@ Let's look at another example. The `.=` rune takes two subexpressions, evaluate
207201> .= 22 11
208202%.n
209203
210−> .= 22 (add 11 11)
211−%.y
212−
213−> .= 22
214− 11
215−%.n
216−
217204> .= 22
218205 (add 11 11)
219206%.y
@@ -262,51 +249,7 @@ The irregular `( )` gate-calling syntax is versatile -- it is also a shortcut fo
26224910
263250```
264251
265−The `( )` gate-calling syntax can be used for gates of any other [arity](https://en.wikipedia.org/wiki/Arity) as well.
266−
267−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.
268−
269−```
270−> =inc |=(a=@ (add 1 a))
271−
272−> (inc 10)
273−11
274−
275−> (inc 15)
276−16
277−```
278−
279−The `a=@` subexpression -- used to define the face and the type of the gate's sample -- is the irregular form of `$=(a @)`:
280−
281−```
282−> =inc |=($=(a @) (add 1 a))
283−
284−> (inc 10)
285−11
286−
287−> (inc 15)
288−16
289−```
290−
291−In the previous chapter you also defined faces in nouns as in the following examples:
292−
293−```
294−> b:[a=15 b=25 c=35]
295−25
296−
297−> c:[a=15 b=25 c=35]
298−35
299−```
300−
301−The `a=15` expression is the irregular form of `^=(a 15)`:
302−
303−```
304−> b:[^=(a 15) ^=(b 25) ^=(c 35)]
305−25
306−
307−> c:[^=(a 15) ^=(b 25) ^=(c 35)]
308−35
309−```
252+The `( )` gate-calling syntax can be used for gates with any number of arguments.
310253
311254You can find other irregular forms in the irregular expression [reference document](/docs/reference/irregular).
312255
@@ -320,9 +263,6 @@ Below we use the `` ` `` symbol to create a cell whose head is null, `~`.
320263> `12
321264[~ 12]
322265
323−> `[12 14]
324−[~ 12 14]
325−
326266> `[[12 14] 16]
327267[~ [12 14] 16]
328268```
@@ -344,229 +284,46 @@ b=[16 18]
344284
345285> ,.+:[a=[12 14] b=[16 18]]
346286[16 18]
347−
348−> ,.+:[a=[12 14] [16 18]]
349−[16 18]
350287```
351288
352289To see other irregular expressions, check the irregular expression [reference document](docs/reference/irregular).
353290
354−## Hoon Style
355−
356−See [Hoon Style Guide](https://urbit.org/docs/learn/hoon/style/).
357−
358−### Rune Expression Body Types
359−
360−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.
361−
362−#### Fixed
363−
364−Some runes have a *fixed* number of subexpressions. For example, the `:-` and `.=` runes each have exactly two.
365−
366−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.
367−
368−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:
369−
370−```
371−> :-(11 22)
372−[11 22]
373−
374−> :+(11 22 33)
375−[11 22 33]
376−
377−> :^(11 22 33 44)
378−[11 22 33 44]
379−```
380−
381−Let's look at these in tall form, using backstep indentation:
382−
383−```
384−> :- 11
385− 22
386−[11 22]
387−
388−> :+ 11
389− 22
390− 33
391−[11 22 33]
392−
393−> :^ 11
394− 22
395− 33
396− 44
397−[11 22 33 44]
398−```
399−
291+## The Standard Library
400292
401−Some other *1-fixed*, *2-fixed*, *3-fixed* and *4-fixed* examples, using `p`, `q`, `r`, and `s` for the subexpressions:
293+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.
402294
403−```
404−|.
405−p
406−
407−=| p
408−q
409−
410−?: p
411− q
412−r
413−
414−%^ p
415− q
416− r
417−s
418−```
419−
420−In optimal usage of backstep indentation the most complicated subexpressions are at the bottom. This helps keep code flow vertical rather than diagonal.
421−
422−#### Running
423−
424−A *running* body doesn't have a fixed number of subexpressions; expressions with running bodies can be arbitrarily long.
425−
426−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.
427−
428−The `:*` rune is used to create a cell of arbitrary length:
429−
430−```
431−> :*(11 22 33)
432−[11 22 33]
433−
434−> :*(11 22 33 44)
435−[11 22 33 44]
436−
437−> :*(11 22 33 44 55)
438−[11 22 33 44 55]
439−```
440−
441−We'll use `:*` to illustrate proper tall form running body style:
442−
443−```
444−> :* 11
445− 22
446− 33
447− 44
448− 55
449− ==
450−[11 22 33 44 55]
451−```
452−
453−More generally:
454−
455−```
456−:* p
457− q
458− r
459− s
460− t
461−==
462−```
463−
464−#### Jogging
465−
466−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 `==`.
467−
468−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.
469−
470−For example:
471−
472−```
473−> ?- `?(%2 %3 %4)`%2
474− %2 %yes
475− %3 %no
476− %4 %no
477− ==
478−%yes
479−```
480−
481−More generally, the *flat jogging* style (preceded by *1-fixed* `p`):
482−
483−```
484−?- p
485− q r
486− s t
487− u v
488−==
489−```
490−
491−A *tall jogging* example (preceded by *1-fixed* `p`):
295+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:
492296
493297```
494−?- p
495− q
496− r
497− s
498− t
499− u
500− v
501−==
298+++ add
299+ ~/ %add
300+ |= [a=@ b=@]
301+ ^- @
302+ ?: =(0 a) b
303+ $(a (dec a), b +(b))
502304```
503305
504−In flat form for *jogging* bodies, subexpression pairs are separated by commas:
505−
506−```
507−$(a +(a), b (dec b), c (add 2 c))
508−```
509−
510−#### Battery
511−
512−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.
513−
514−Here's an example of a *battery* body:
515−
516−```
517−|%
518−++ arm-1
519− %p
520−++ arm-2
521− %q
522−++ arm-3
523− %r
524−--
525−```
306+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`.
526307
527−## Motivation
308+## Reference Materials
528309
529−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.
530−
531−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*.
532−
533−### Terminator piles
534−
535−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 `+`:
536−
537−```
538−(+ 22 (+ 22 (+ 22 (+ 22 22))))
539−```
540−
541−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:
542−
543−```
544−> (add 22 (add 22 (add 22 (add 22 22))))
545−110
546−```
547−
548−...but you are never forced to do so. There is always a semantically equivalent alternative syntax without them:
549−
550−```
551−> %+ add 22
552− %+ add 22
553− %+ add 22
554− %+ add 22 22
555−110
556−```
310+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:
557311
558−### Indentation creep
312+- The [Runes](/docs/reference/hoon-expressions/) page will show you how to use any Hoon rune.
313+- The [Cheat sheet](/docs/reference/cheat-sheet/) is a more compact place to look up rune expressions.
314+- 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.
315+- 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.
559316
560−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.
317+### Debugging
561318
562−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.
319+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.
563320
564−### Feature/label confusion
321+There are a couple useful runes associated with debugging:
565322
566−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.
323+`!:` (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.
567324
568−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.
325+`~&` (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.
569326
570−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.
327+But there are more. Check out the aforementioned [troubleshooting](/docs/reference/troubleshooting/) page to see other handy debugging runes and how to use them.
571328
572−### [Next Lesson: Simple One-Gate Programs](../simple-one-gate-programs)
329+### [Next Lesson: The Subject and Its Legs](../the-subect-and-its-legs)