the diagnostics catalog

in most languages the error messages are an afterthought—the thing you see when something else went wrong. in kanso they are the product. the founding principle is that anything a style guide, a linter, or a code review would enforce by convention is instead a compile error with a caret under it, so the compiler treats waste and disorder the way other compilers treat type mismatches. that principle is only as good as the diagnostics that carry it, and this appendix is the complete list: every error the compiler emits, grouped by kind, each with the smallest program that triggers it and the exact text you get back.

errors arrive under a tag in square brackets that names the family the rule belongs to—formatting, unused, name, dispatch, signature, syntax, and, at the far edge, endpoint. the first six are caught by kanso check before a single line runs. the last one names a failure that only a running program can produce. every sample below was fed to the real compiler, and every diagnostic on this page is copied from the machine, not typed from memory.

anatomy of a diagnostic

one specimen, read part by part. this program binds x and never reads it:

x = 1
print "hi"

error[unused]: unused binding `x`
  --> unused_binding_check.kso:1:1
   1 | x = 1
       ^

four parts, always in this shape. the first line is the tag—error[unused]—followed by the rule stated as a fact about the language, not a suggestion. the second line, after -->, is the location: file, line, column. then the offending source line is reprinted with its number. finally a caret points at the exact column named in the location. every diagnostic in this catalog is that same four-part object; once you can read one, you can read all of them.

error[formatting]—spacing and invisibles

the formatting family is the largest, because canonical form is not a convention layered over the grammar—it is the grammar, and a program has exactly one legal rendering. these first rules protect the layer you can barely see: spaces, and the characters that hide between tokens. start with the one that carries no visible mark at all. a space after the closing quote:

print "hi" 

error[formatting]: trailing whitespace is not part of the canonical grammar
  --> trailing_ws_check.kso:1:11
   1 | print "hi" 
                 ^

spacing around = is fixed at exactly one space on each side. cram it and the compiler reports both sides—two carets, one per missing space:

answer=42
print "{answer}"

error[formatting]: canonical form requires exactly one space here
  --> cramped_binding_check.kso:1:7
   1 | answer=42
             ^
error[formatting]: canonical form requires exactly one space here
  --> cramped_binding_check.kso:1:8
   1 | answer=42
              ^

the reflex you brought from every c-descended language is parentheses hugging a call. a call is a name, one space, its arguments, and the compiler says so by name:

print("hi")

error[formatting]: application is a space, so `print x` calls `print` — `print(x)` reads as `print` applied to nothing, then a parenthesised `x`
  --> paren_call_check.kso:1:6
   1 | print("hi")
            ^

and the other reflex: a comma between things. there are no commas in kanso, anywhere—arguments, list elements, and record fields are all space-separated:

total = sum [1, 2]
print "{total}"

error[formatting]: kanso has no commas; enumerations are space-separated
  --> commas_check.kso:1:15
   1 | total = sum [1, 2]
                     ^

a line has a hard ceiling of eighty characters. the diagnostic counts them for you and points at column eighty-one, the first one over the line:

print "this string pads the line out well past the canonical width limit of eighty"

error[formatting]: a line holds at most 80 characters — this one has 83
  --> line_length_check.kso:1:81
   1 | print "this string pads the line out well past the canonical width limit of eighty"
                                                                                       ^

error[formatting]—one true name

every identifier is snake_case, all lowercase. this protects a single reading of every name: no debate over whether the constant is maxRetries, MaxRetries, or max_retries, because two of the three won't parse. a capital letter is flagged at its definition and again at every use, so you fix the name once and both carets disappear together:

myName = 1
print "{myName}"

error[formatting]: identifiers are snake_case, all lowercase, always
  --> snake_case_check.kso:1:3
   1 | myName = 1
         ^
error[formatting]: identifiers are snake_case, all lowercase, always
  --> snake_case_check.kso:2:11
   2 | print "{myName}"
                 ^

error[formatting]—order and separation

a file has a fixed shape: types come first, then functions and constants. within those groups the order is yours to choose, so a helper can sit beside the thing it helps and the entry point can stay where a reader will look for it. put a type after a function and the compiler tells you which way it must move:

fn use_it t
  t

type thing
  size

pub play = print "x"

error[formatting]: canonical order places type declarations before functions; move `thing` up
  --> type_order_check.kso:4:6
   4 | type thing
            ^