canonical form
most languages ship a formatter—a second program that rewrites your source into the house style. kanso ships none, because the grammar itself fixes the layout. a program has exactly one legal rendering, and every deviation is a compile error with a caret under it. this appendix is the reference for that law: each rule stated plainly, the reason it exists, and the diagnostic you get when you break it. every broken sample here was run through kanso check; every error text is copied from its output.
the founding principle is one sentence: anything a style guide, linter, or code review would enforce by convention, kanso enforces by making the alternative a compile error. so there is no formatter to configure or run, and a diff between two versions of a file never contains reflowed lines or whitespace changes.
here is a whole, legal file. read it, then spend the rest of the appendix learning why each character sits where it does:
type circle
r
fn area (circle r)
r * r * 3.14159
print "area of r=2: {area (circle 2.0)}"
area of r=2: 12.56636
whitespace, two at a time
indentation is spaces, and the only legal depths are zero and two-per-level. a body indents its lines by two more spaces than the header that owns them. three spaces, four spaces, one—all rejected, with the exact count named back to you:
x = 1
print "{x}"
error[formatting]: indentation must be 0 or 2 spaces, found 1
--> indent_check.kso:1:1
1 | x = 1
^
error[formatting]: indentation must be 0 or 2 spaces, found 1
--> indent_check.kso:2:1
2 | print "{x}"
^
a tab is not part of the grammar at all. the width of a tab depends on whose editor renders it, and a language with one rendering per program cannot admit a character whose meaning is a display setting:
print "hi"
error[formatting]: tabs are not part of the canonical grammar; indent with spaces
--> tabs_check.kso:1:1
1 | print "hi"
^
within a line, spacing is fixed too. exactly one space sits on each side of =, and one space separates a call from its argument. no more, no fewer, and none glued away entirely. cram a binding and the compiler points at both the missing space before and the missing space after:
answer=42
print "{answer}"
error[formatting]: canonical form requires exactly one space here
--> spacing_check.kso:1:7
1 | answer=42
^
error[formatting]: canonical form requires exactly one space here
--> spacing_check.kso:1:8
1 | answer=42
^
whitespace you cannot see is still in the file. trailing whitespace at the end of a line has no meaning, shows up in diffs, and is refused:
print "hi"
error[formatting]: trailing whitespace is not part of the canonical grammar
--> trailing_check.kso:1:11
1 | print "hi"
^
no commas, no call parentheses
application is juxtaposition. f a b is a call to f with two arguments, and the separator is a single space. there are no commas anywhere: in argument lists, list literals or patterns. bring the comma from another language and kanso names the habit:
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]
^
likewise there are no parentheses wrapping a call's arguments. parentheses group sub-expressions—f (g x) y—and do nothing else, so print("hi") reads as print applied to nothing:
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`
--> call_paren_check.kso:1:6
1 | print("hi")
^
parentheses that group nothing are refused as well: if an expression parses the same without them, the compiler asks you to take them out. two kinds of chain need them anyway. &, | and ^ share one level, so a chain that mixes them must say which goes first. and binds tighter than or, but a condition that mixes the two is refused until parentheses say which part goes first, so nobody has to remember the table to read it:
fn ready signed paid admin
signed and paid or admin
pub play = print "{ready true false true}"
error[syntax]: `and` and `or` meet without parentheses — parenthesize the part that goes first, as in `(a and b) or c`
--> and_or_check.kso:2:19
2 | signed and paid or admin
^
the answer is (signed and paid) or admin, and those parentheses stay, because the line without them does not compile.
one order per file
wherever order carries no meaning, canonical order is mandatory, so that two programs differing only in shuffle are impossible: imports, the members of a typeset, the fields of a keyed read. declaration order is not one of those places—it carries narrative, and it stays yours. what the file does fix is the two groups: type declarations come first, then functions and constants. put a type below a function and the compiler tells you which one to move and where:
fn use_it t
t
type thing
size
pub play = print "x"
error[formatting]: canonical order places type declarations before functions; move `thing` up
--> order_types_check.kso:4:6
4 | type thing
^
and it reaches into a keyed destructuring read, where you name a subset of fields to pull out. the names you list are a set, so they are alphabetized like any other:
type user
admin
name
pub play =
{ name admin } = user false "clay"
print "{name} {admin}"
error[formatting]: keyed reads list fields in alphabetical order: `admin` before `name`
--> keyed_order_check.kso:6:10
6 | { name admin } = user false "clay"
^
blank lines carry meaning
a blank line is part of the syntax, so its use is exact. top-level declarations are separated by exactly one blank line. run two declarations together and the compiler asks for the separator:
fn greet _
print "hi"
fn wave _
print "yo"
pub play = greet 0 . wave
error[formatting]: exactly one blank line separates top-level declarations
--> blank_between_check.kso:3:1
3 | fn wave _
^
inside a body, blank lines are banned entirely. a body is one uninterrupted run of statements; the moment you want to group some of them apart with a blank line, you are describing structure the grammar already has words for—bindings, and the chain words—and it wants those words, not a gap:
fn greet _
x = 1
print "{x}"
pub play = greet 0
error[formatting]: blank lines may not appear inside a body
--> blank_body_check.kso:4:1
4 | print "{x}"
^
a file may open with a header comment: a block of comment lines about the whole file, then exactly one blank line, then the code. the blank line keeps the header from reading as a comment on the first declaration. a second blank line is refused, and so is a blank line above the header:
# Weekly totals, read from the ledger.
fn total xs
list/sum xs
pub play = print "{total [1 2 3]}"
error[formatting]: one blank line separates the header comment from the code
--> header_check.kso:3:1
3 |
^
eighty columns, and the continuation line
a line holds at most eighty characters. the diagnostic even counts them for you:
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
--> width_check.kso:1:81
1 | print "this string pads the line out well past the canonical width limit of eighty"
^
width is rendering only—it never changes how many statements a body has. an over-wide statement stays one statement, wrapped across continuation lines. the continuation forms are the tokens that express ordering everywhere else: . for a data-flow pipe, and .>, .! and .? for the three chain words. each step lands on its own line, indented two past the statement, one step per line.
here is a sequence too wide for one line. its first step stays on the statement's own line, and the .> step that follows drops to a continuation line at indent plus two:
print "steeping the sencha in the small clay pot for exactly ninety seconds"
.> (_ -> print "pouring the water in a thin stream from above the first cup")
steeping the sencha in the small clay pot for exactly ninety seconds
pouring the water in a thin stream from above the first cup
and here is a pipe too wide for one line, wrapped onto continuation lines. the whole thing is still a single binding of ranked:
import "std/list"
ranked = [40 15 8 23 42 16 4 108 71 55 90 33 27 61 19 77 88 100 200]
. list/sort
.> list/sum
print "sum of the sorted roster: {ranked}"
sum of the sorted roster: 1077
because there is one rendering, the wrap is not optional. if a statement fits on one line, it must be on one line—wrapping something that fits is "needless continuation," and the compiler tells you the width it would occupy unwrapped:
total = [9 1 8 2 7] . sort
. sum
print "sum: {total}"
error[formatting]: needless continuation: this statement fits on one line (32 characters)
--> needless_wrap_check.kso:2:3
2 | . sum
^
a list or map literal too long for its line spans lines instead, one element to a line, with the closing bracket alone at the indent of the line that opened it. chapter 02 shows the form. the same rule applies to it: a literal that fits on one line must be written on one line, and the diagnostic gives the width it would take:
steps = [
"boil"
"steep"
"pour"
]
print "{steps}"
error[formatting]: this list fits on one line (31 characters) — a list spans lines only when it does not
--> span_short_check.kso:1:9
1 | steps = [
^
a literal with a comment among its elements cannot be written on one line, because a comment runs to the end of its line, so it spans lines whatever its width.
names: snake_case, lowercase, always
identifiers are lowercase snake_case, with no exceptions and no second convention to remember. no camelCase, no PascalCase, no SCREAMING_CONSTANTS. a single naming scheme means a name looks identical everywhere it appears, and a reader never wonders whether case carries meaning—it does not:
myName = 1
print "{myName}"
error[formatting]: identifiers are snake_case, all lowercase, always
--> case_check.kso:1:3
1 | myName = 1
^
error[formatting]: identifiers are snake_case, all lowercase, always
--> case_check.kso:2:11
2 | print "{myName}"
^
one convention you may have expected is absent: there is no leading-underscore rule for privacy. a top-level name is module-private by default, and the leading keyword pub marks the ones that are api surface—visibility runs on that keyword, not on how you spell the name. the underscore _ means exactly one thing, a discard in a pattern, and nothing about it says "private."
strings are double-quoted
string literals use double quotes. the lexer doesn't recognize a single quote as a string delimiter at all, so it just names the character it choked on:
print 'hi'
error[syntax]: unexpected character `'`
--> quote_check.kso:1:7
1 | print 'hi'
^
inside a double-quoted string, {braces} interpolate, and the braces take any expression—a name, arithmetic, a call. you have seen this throughout the appendix: "sum of the sorted roster: {ranked}", "area of r=2: {area (circle 2.0)}". there is one string syntax, one interpolation syntax, and no format-string mini-language bolted on beside it.
in short: two-space indents, one space around =, alphabetical imports, nothing trailing, eighty columns. the compiler accepts no other layout, so there is nothing left to decide.
you can now read any diagnostic in the error[formatting] family and know it names a rule with exactly one legal answer, and you can write a file that kanso check passes on the first try: two-space indents, one space around every = and operator, no commas and no call parentheses, parentheses only where they group something, types before functions, one blank line between declarations and none inside a body, one under a header comment, eighty columns with ., .>, .! and .? continuation lines when a statement runs long, a list or map one element to a line when it runs long, snake_case names, and double-quoted strings. each of these is enforced by the compiler, which is why a kanso diff shows only changes someone decided to make.
exercises
- take
wrap_pipe.ksoand remove enough elements from the list that therankedbinding would fit on one line unwrapped. predict which diagnostickanso checkproduces before you run it, then confirm. - write a library file with a function named
buildfollowed by a type namedwidget. runkanso checkand read what it asks you to move. then put two types in reverse alphabetical order and check again: which orderings does the compiler enforce, and which does it leave to you? - a body has a binding you want to set visually apart from the effects below it. you reach for a blank line and the compiler rejects it. what does the grammar offer instead, and what does that say about when a blank line would ever have been the right tool?
- construct a single statement that is exactly 80 characters and one that is exactly 81. verify the boundary is where the diagnostic claims it is, and read the character count it reports back.