@@ -1,182 +0,0 @@
6−Ideally your Hoon works perfectly the first time. But...
10−When you get a syntax error, you'll see a message like
16−This is a line and column number; more exactly, the line and
17−column of the first byte the parser couldn't interpret as part of
18−a correct Hoon file. These values are always correct.
20−Usually, the line and column tell you everything you need to
21−know. But the worst-case scenario for a syntax error is that,
22−somewhere above, you've confused Hoon's tall form by using the
23−wrong fanout for a rune. For example, `%+` ([**cenlus**](@/docs/reference/hoon-expressions/rune/cen.md#cenlus),
24−a function call whose sample is a cell) has three subhoons:
32−But if you make a mistake and write
39−the parser will eat the next hoon below and try to treat it as a
40−part of the `%+`. This can cause a cascading error somewhere
41−below, usually stopped by a `==` or `--`.
43−When this happens, don't panic! Binary search actually works
44−quite well. Any hoon can be stubbed out as `!!`. Find the
45−prefix of your file that compiles, then work forward until
46−the actual error appears.
50−Now your code parses but doesn't compile.
54−Your first step should be to put a `!:` ("zapcol") rune at the
55−top of the file. This is like calling the C compiler with `-g`;
56−it tells the Hoon compiler to generate tracing hoons.
58−Bear in mind that `!:` breaks tail-call optimization. This is a
59−bug, but a relatively low-priority bug. `!.` turns off `!:`.
60−Note that `!:` and `!.` are hoon-level, not file-level; you can
61−wrap any hoon in either.
65−If you have `!:` on, you'll see an error trace, like
68−/~zod/home/0/gen/hello:<[7 3].[11 21]>
69−/~zod/home/0/gen/hello:<[8 1].[11 21]>
70−/~zod/home/0/gen/hello:<[9 1].[11 21]>
71−/~zod/home/0/gen/hello:<[10 1].[11 21]>
72−/~zod/home/0/gen/hello:<[11 1].[11 21]>
73−/~zod/home/0/gen/hello:<[11 7].[11 21]>
77−The bottom of this trace is the line and column of the hoon which
78−failed to compile, then the cause of the error (`nest-fail`).
80−Hoon does not believe in inundating you with possibly irrelevant
81−debugging information. Your first resort is always to just look
82−at the code and try to figure out what's wrong. This practice
83−strengthens your Hoon muscles.
85−(Consider the opposite extreme; imagine if you had a magic bot
86−that always fixed your compiler errors for you. Pro: no time
87−wasted on compiler errors. Con: you never learn Hoon.)
91−Moral fiber is all very well and good, but sometimes you're
92−stumped. Couldn't the compiler help a little? These messages do
93−mean something. Here are the three most common:
97−This is a type mismatch (`nest` is the Hoon typechecker). It
98−means you tried to pound a square peg into a round hole.
100−What was the peg and what was the hole? Hoon doesn't tell you by
101−default, because moral fiber, and also because in too many cases
102−trivial errors lead to large intimidating dumps. However, you
103−can use the `~!` rune ([**sigzap**](@/docs/reference/hoon-expressions/rune/sig.md#sigzap)) to print the type of
104−any hoon in your stack trace.
106−For instance, you wrote `(foo bar)` and got a `nest-fail`. Change
115−You'll get the same `nest-fail`, but this will show the type of
116−`bar`, then the type of the sample of the `foo` gate.
120−A `find.foo` error means limb `foo` wasn't found in the subject.
121−In other words, "undeclared variable."
123−The most common subspecies of `find` error is `find.$`, meaning
124−the empty name `$` was not found. This often happens when you
125−use a hoon that does not produce a gate/mold, as a gate/mold. For
126−instance, `(foo bar)` will give `find.$` if `foo` is not actually a
129−### `mint-vain` and `mint-lost`
131−These are errors caused by type inference in pattern matching.
132−`mint-vain` means this hoon is never executed. `mint-lost` means
133−there's a case in a `?-` ([**wuthep**](@/docs/reference/hoon-expressions/rune/wut.md#wuthep)) that isn't handled.
137−If your code crashes at runtime or overflows the stack, you'll
138−see a stack trace that looks just like the trace above. Don't
139−confuse runtime crashes with compilation errors, though.
141−If your code goes into an infinite loop, kill it with `ctrl-c` (you'll
142−need to be developing on the local console; otherwise, the
143−infinite loop will time out either too slowly or too fast). The
144−stack trace will show what your code was doing when interrupted.
146−The counterpart of `~!` for runtime crashes is `~|`
147−([**sigbar**](@/docs/reference/hoon-expressions/rune/sig.md#sigbar)):
154−If `(foo bar)` crashes, the value of `foo` is printed in the
155−stack trace. Otherwise, the `~|` has no effect.
159−The worst possibility, of course, is that your code runs but does
160−the wrong thing. This is relatively unusual in a typed
161−functional language, but it still happens.
163−`~&` ([**sigpam**](@/docs/reference/hoon-expressions/rune/sig.md#sigpam)) is Hoon's debugging printf.
164−This pretty-prints its argument:
171−will always print `foo` every time it executes. A variant is
172−`~?` ([**sigwut**](@/docs/reference/hoon-expressions/rune/sig.md#sigwut)), which prints only if a condition is
176−~? =(37 (lent foo)) foo
180−For now, you need to be on the local console to see these debug
181−printfs (which are implemented by interpreter hints). This is a
182−bug and, like all bugs, will be fixed at some point.