The Adder Language Reference

Cheat Sheet

Need a quick reminder of how to write something? These two pages tour the entire Adder language through small, complete programs you can run right away. Each section links to the handbook chapter where you can explore the full details.

Declarations

const declares a fixed value, var declares mutable state, and <- creates a reactive binding or hardware output that stays in sync automatically. Inside a handler or its loops, name = expression updates existing var state. See Types and Declarations.

type Lane = Number<0...39>              // a friendly nickname for a type
enum Mode
  case title, playing, over
end
struct Speed(x: Number<-3...3>, y: Number<-3...3> = 0)
const limit = 40                              // a constant: fixed before the program runs
var lane: Lane = 0                      // state: remembered from frame to frame
var mode: Mode = .title
var speed: Speed = (x: 1)
fn mirror(x: Lane): Lane                // a pure function: same inputs, same answer
  Lane.last - x
end
op change(value: Lane)                  // an op: a calculation that remembers past frames
  value - value.previous(from: value)
end
far <- mirror(lane)                     // a binding: updates whenever lane changes
moved <- change(lane) != 0
System.screen.border <- if moved then .yellow else .black end
System.screen.text[0][0..<2] <- far.digits(2)
when System.keyboard.space.pressed      // a handler: runs when an event happens
  lane = lane +% 1
  mode = mode.next()
end

A struct block can bundle fields and helper functions together (mut fn can update the struct's own var fields), and at places a value at a specific memory address.

struct Score
  step: Number<u8>
  var points: Number<0...999> = 0
  mut fn award()
    points = points +| step
  end
  fn text(): [3 of Char]
    points.digits(3)
  end
end
var score = Score(step: 10)
seen: Number<u8> at 0xC000
when System.keyboard.space.pressed
  score.award()
end
System.screen.text[0][0..<3] <- score.text()
System.screen.border <- Color(seen % 16)

To split a larger project across files, include "lib/world" brings another file from the project into your program.

Numbers

Every number in Adder knows the range of values it can hold. Write a custom range like Number<0...9> or Number<0..<40>, or pick a hardware storage format directly (u8, i8, u16, i16 for whole numbers, and u8.8, i8.8, u16.8, i16.8 for fractions in steps of 1/256). Writing Number by itself gives you a two-byte whole number from -32,768 to 32,767. See Numbers and Expressions.

var a: Number<u8> = 0xFF                // also 255 or 0b1111_1111
var b: Number<0...9> = 5
var c: Number<0..<40> = 0
var d: Number<-2.0...2.0> = 0.5
const mask = 0b0000_0101
when System.screen.frame
  b = b +% 1                            // wraps around: 9 steps back to 0
  c = c +| 3                            // clamps at the top: stops at 39
  a = a.bitwise_and(mask).shift_left(1)
end
whole <- d.floor()                      // also round() and ceil()
byte <- Number<u8>(b)                   // an explicit conversion
System.screen.border <- Color(b)

When a calculation reaches the edge of a variable's range, the operator you choose decides what happens next:

Multiplication (*) is always checked. If you want a product to wrap around, take its remainder with %, such as (a * b) % 16.

Control

Use if ... then ... end for conditions and match for branching on cases or condition tables. Inside a when handler, you can filter events with a second when, bail out early with guard, or pause across frames with wait. See Events and Handlers and Statements.

var lives: Number<0...3> = 3
var score: Number<0...99> = 0
shade <- if lives == 1 then Color.red else Color.black end
System.screen.border <- match
  when lives == 0 -> Color.gray
  else -> shade
end
when System.keyboard.space.pressed when lives > 0
  lives = lives - 1
end
when lives.changed
  guard lives == 0                      // stops the handler here unless true
  score = 0
end
when start
  forever                               // repeats; every turn must reach a wait
    wait(ms: 500)                       // or wait(30) frames, wait(seconds: 2)
    score = score +% 1
  end
end

Among declarations, a match or an if holds declarations, and what a case declares exists only while the case matches. A match divides the program into cases—such as a title screen and a play screen—where only the active case's bindings and handlers run. Cases can add when condition; without a value after match, ordered when condition -> lines and a final else -> choose the case.

enum Scene
  case title, game
end
var scene: Scene = .title
match scene
  title ->
    System.screen.text[11][15..<25] <- "PRESS FIRE"
    when System.joystick[2].fire.pressed
      scene = .game
    end
  game ->
    System.screen.border <- .green
    when start
      wait(seconds: 2)
      wait System.joystick[2].fire.pressed
      scene = .title
    end
end

Lists and Slices

[n of T] is a fixed-length list of n items. Put a range in brackets to take a window (slice) into a list, or two ranges to take a 2D rectangle from a grid of rows. See Lists and Expressions.

var xs: [8 of Number<u8>] = [3, 1, 4, 1, 5, 9, 2, 6]
const grid = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
var left: Number<0...4> = 0
window <- xs[left..<(left + 4)]         // a 4-item window whose start can slide
corner <- grid[0..<2, 1..<3]            // a 2-by-2 rectangle
big <- xs.filter(n -> n > 3)            // keeps matching items as Number<u8>?
doubled <- xs.map(n -> n * 2)
all_of <- xs.sum()
fn add_up(values: [n of Number<u8>]): Number<u16>
  var t: Number<u16> = 0
  for v in values
    t = t + v
  end
  t
end
part <- add_up(window)
when System.keyboard.space.pressed
  xs[0] = 7
  left = (left + 1) % 5
end

Optionals

Add ? to any type (T?) when a place might either hold a value or be empty (nil). See Optionals.

var held: Number<u8>? = nil
when System.keyboard.space.pressed
  held = 7
end
when System.keyboard.delete.pressed
  if n = held then                      // unwraps and names the value when present
    held = n -| 1
  end
end
shown <- held ?? 0                      // uses 0 when held is nil
System.screen.border <- if held != nil then Color(shown % 16) else .black end

Devices

Every part of the Commodore 64 lives under System—no hex addresses required. See The System Device Tree.

bat: Number<0...296> <- (System.joystick[2].dx * 4).sum(from: 136)
held <- System.joystick[2].fire
beat <- System.clock.interval(seconds: 0.25)
var hue: Number<0...15> = 0
when beat
  hue = hue +% 1
end
when System.keyboard.space.pressed
  System.sound[1].voice[2].play(Tone(.c6, decay: .short))
end
System.screen.border <- Color(hue)
System.screen.background <- .black
System.screen.text[0][0..<5] <- "SCORE"
System.screen.ink[0][0..<5] <- .yellow
System.screen.sprite[0] <- (x: bat, y: 170, color: .white)
System.sound[1].voice[1] <- if held then Tone(.c4) else .silence end

const picture = System.screen.canvas()
const badge = Picture(["XXXXXXXX", "X......X", "X......X", "XXXXXXXX"])
x: Number<0...312> <- System.joystick[2].dx.sum(from: 80)
picture.ink <- .yellow
picture.paper <- .blue
picture.drawings <- [badge.place(x: x, y: 40), Text(content: "SCORE").place(x: 16, y: 8)]

const log = System.screen.region(row: 1, height: 3, width: 12)
var items: Number<0...999> = 0
when System.screen.frame.every(30)
  items = items +% 1
  log.println(items.digits(3))
end

Interrupt Routines

When you want a tiny block of 6510 assembly to run at a specific raster line on screen or on a millisecond timer, wrap it in an interrupt handler. The compiler wires up the interrupt and budgets its cycles in every frame. See Interrupt Routines.

when System.screen.interrupt(line: 100)   // once a frame, when the beam hits line 100
  asm
    inc System.screen.border
  end
end
when System.clock.interrupt(ms: 20)       // every 20 milliseconds
  asm
    inc ticks
  ticks:
    .byte 0
  end
end

Costs

The compiler proves before your program runs that every frame's work finishes before the next frame begins. When a heavy loop needs a speed boost, put fast before a handler, function, op, binding, or case to spend a few extra bytes of memory in exchange for faster code. See Costs and the Frame.

var weights: [64 of Number<u8>] = 3
var levels: [64 of Number<u8>] = 5
var mix: Number<u16> = 0
fast when System.screen.frame
  var acc: Number<u16> = 0
  for i in 0..<64
    acc = acc +% weights[i] * levels[i]
  end
  mix = acc
end
System.screen.border <- Color(mix % 16)

You can also inspect every line's exact byte count and worst-case cycle estimate from the terminal, or compare two versions of a program without running an emulator:

bun tools/costs.ts ../game.adder --listing
bun tools/cost-diff.ts ../game.adder --at HEAD

fast forces the listed larger, faster forms on a code head; small keeps its compact forms. Both can mark functions, ops, handlers, bindings, case patterns and regions. The innermost mark decides, including an explicitly marked body copied at a call.

About the Language Reference

Think of this reference as your desk manual for Adder and the Commodore 64. Each chapter takes one part of the language and shows you how to write it, what it means at runtime, which types and number ranges it works with, what it costs in bytes and processor cycles, and how the compiler helps you catch mistakes early.

If you would rather learn by building a small arcade game from scratch, begin with the Adder Quickstart and come back here whenever you are curious about the full details of a feature.

Examples

Every framed code block in this handbook is a complete, runnable Adder program. You can paste it into the Lab or save it to a .adder file and run it immediately:

System.screen.border <- Color.light_blue

Whenever a chapter explains a rule that the compiler checks before your program runs, it names the message key in backticks, such as wrongType. You can look up any key in Diagnostics to see the exact message the compiler gives and how to fix it.

Grammar Notation

Each construct includes a small grammar box that shows all the ways you can write it. Every line of the form name ::= form defines what name stands for. When a construct has several forms, | separates them, and a line starting with | continues the choices from the line above.

example ::= 'when' event ( 'when' condition )? newline statement* 'end'

Here is how to read the symbols inside a grammar box:

The grammar tells you which programs have a valid shape. Once a program's shape is valid, the compiler checks its types, number ranges, and frame timing—and each chapter explains how those checks work. The Grammar Summary gathers every grammar box from the handbook into one place for quick lookup.

Lexical Structure

Before your program can light up the screen or play a note, the compiler reads your source text character by character and groups those characters into tokens: names, reserved words, literals, operators and punctuation. It scans each line from left to right and always takes the longest run of characters that forms a valid token at each spot—so format is read as one whole name rather than the reserved word for followed by mat, and <= is one operator rather than < followed by =.

Source Text

An Adder source file is plain ASCII text up to 65,535 characters long—plenty of room for a brisk arcade game or a musical toy, while still fitting comfortably in the machine's memory. Outside comments, every character you type belongs either to a token, to a string literal, or to the whitespace between tokens. If a stray character slips in, the compiler points it out by name so you can sweep it away.

Spaces, tabs and carriage returns simply separate tokens and carry no hidden meaning. Indentation is purely for your own eyes: every block closes explicitly with the word end, never with a shift in indentation, so you can lay out your code however it reads best to you.

Comments

A comment starts with // and runs to the end of the line. The compiler skips right past it, so you can jot down any characters or notes you like inside. Adder has no multi-line comment marker; for a longer note, just start each line with //.

// The border steps through its sixteen colors.
var hue: Number<0...15> = 0 // the color shown now
when System.screen.frame
  hue = hue +% 1
end
System.screen.border <- Color(hue)

Lines

A line break finishes a declaration or a statement, giving each line a single job. Adder uses no semicolons and keeps one declaration to a line; if you pack two declarations onto one line or end a line with a semicolon, the compiler catches it right away.

When a call, a struct value or a list grows long, you can split it across lines inside an open ( or [ at three clean spots:

• right after the opening bracket;
• right after a comma;
• right after a finished item, just before the closing bracket.

You are welcome to leave a trailing comma on the last item of a call, a struct value or a list—handy when you rearrange lines later. A value if or match inside brackets keeps its own multi-line layout.

System.screen.text <- Text(
  row: 2,
  col: 4,
  content: "Hello",
)

If a line breaks anywhere else inside brackets—such as right after a colon or an operator—the compiler flags the break and names the bracket that is still waiting to close.

Brackets can nest up to 16 levels deep within a single expression. If an expression burrows deeper than that, the compiler stops with nestingExpression and invites you to pull part of the calculation out onto an earlier line with its own name.

line-break-in-brackets ::= '(' newline | '[' newline
                         | ',' newline
                         | item newline ( ')' | ']' )

Names

A name starts with an ASCII letter (a to z or A to Z) or an underscore, followed by any mix of letters, digits and underscores. Case matters: score and Score are two distinct names.

name           ::= name-head name-character*
name-head      ::= 'a' to 'z' | 'A' to 'Z' | '_'
name-character ::= name-head | '0' to '9'

You can tell a type from a value at a glance by its very first character:

• a value name—for a constant, variable, binding, function, op or parameter—starts with a lowercase letter or an underscore;
• a type name—for a type, enum or struct—starts with a capital letter.

If those get swapped, the compiler gently steers you back: a capitalized value declaration triggers capitalizedDeclaration, and a lowercase type declaration triggers aliasName, enumName or structName.

Reserved words (listed under Reserved Words) cannot be used as names, and any name starting with two underscores (__) is reserved for the compiler's own machinery (internalName). A handful of built-in names mean the exact same thing in every program, so the compiler keeps them safe from redeclaration with builtinName: the built-in types, the root word System that starts every device path, and the scratch workspace used in assembly. Built-in member names like count, sum, min, max, digits and random, on the other hand, are yours to use freely: you can name a constant, variable, function or parameter count, and scores.count() will still give you the built-in count of scores.

Reserved Words

These keywords form the backbone of Adder's grammar and are never used as ordinary names. Number opens every numeric type, and the eight storage format names appear only inside Number<...>, though none of them may name a value.

keyword     ::= 'and' | 'asm' | 'at' | 'break' | 'case' | 'const' | 'else' | 'end' | 'enum'
              | 'false' | 'fast' | 'small' | 'partial' | 'fn' | 'for' | 'forever' | 'guard' | 'if' | 'in'
              | 'include' | 'match' | 'mut' | 'nil' | 'not' | 'Number' | 'of' | 'on'
              | 'op' | 'or' | 'output' | 'start' | 'struct' | 'then' | 'true' | 'type'
              | 'var' | 'wait' | 'when' | 'work'
format-name ::= 'u8' | 'i8' | 'u16' | 'i16' | 'u8.8' | 'i8.8' | 'u16.8' | 'i16.8'

Words Inside Assembly

Step inside an asm block and the vocabulary shifts to match the processor. Inside asm, the 6510 instruction mnemonics below become reserved words, while guard, start, then, for, break, wait and forever relax into ordinary names. Outside asm, those instruction mnemonics are free for your own variables—so calling a counter inc or dex in regular Adder code is completely fine. The header words writes, runs and cycles are reserved only on the opening line of an asm block, where they introduce its optional clauses, and the addressing marks below belong exclusively to assembly lines. Inside assembly, hexadecimal numbers wear a leading $ and binary numbers wear a leading %. Turn to the Assembly chapter for the full tour.

assembly-word    ::= 'writes' | 'runs' | 'cycles' | '#' | ',x' | ',y' | '.lo' | '.hi' | '.byte' | '.text'
instruction-name ::= 'adc' | 'alr' | 'anc' | 'and' | 'arr' | 'asl' | 'asr' | 'axs'
                   | 'bcc' | 'bcs' | 'beq' | 'bit' | 'bmi' | 'bne' | 'bpl' | 'brk'
                   | 'bvc' | 'bvs' | 'clc' | 'cld' | 'cli' | 'clv' | 'cmp' | 'cpx'
                   | 'cpy' | 'dcp' | 'dec' | 'dex' | 'dey' | 'eor' | 'inc' | 'inx'
                   | 'iny' | 'isb' | 'isc' | 'jmp' | 'jsr' | 'lax' | 'lda' | 'ldx'
                   | 'ldy' | 'lsr' | 'nop' | 'ora' | 'pha' | 'php' | 'pla' | 'plp'
                   | 'rla' | 'rol' | 'ror' | 'rra' | 'rti' | 'rts' | 'sax' | 'sbc'
                   | 'sbx' | 'sec' | 'sed' | 'sei' | 'slo' | 'sre' | 'sta' | 'stx'
                   | 'sty' | 'tax' | 'tay' | 'tsx' | 'txa' | 'txs' | 'tya'

Literals

A literal spells out a fixed value right in your code: a number, a quoted string of text, a yes-or-no flag or nil.

literal ::= whole-literal | decimal-literal | string-literal | 'true' | 'false' | 'nil'

Whole-Number Literals

You can write a whole number in everyday decimal digits, in hexadecimal after 0x, or in binary after 0b—perfect when you are masking bits or laying out hardware flags. Both the prefix letters (0x, 0X, 0b, 0B) and the hexadecimal digits (a–f or A–F) accept uppercase or lowercase. In hexadecimal and binary literals, you can tuck a single underscore between digits to group nybbles or bytes cleanly (0b0000_0101). Decimal literals are written as plain digits without underscores.

whole-literal  ::= decimal-digits
                 | '0x' hex-digit ( '_'? hex-digit )*
                 | '0b' binary-digit ( '_'? binary-digit )*
decimal-digits ::= decimal-digit+
decimal-digit  ::= '0' to '9'
hex-digit      ::= decimal-digit | 'a' to 'f' | 'A' to 'F'
binary-digit   ::= '0' | '1'

How you write the literal never locks in its storage width or type. 5, 0x05 and 0b0000_0101 are the exact same number five; the spot that receives the number decides how it is stored, as Types explains.

const north_and_south: Number<u8> = 0b0000_0101
var open_paths: Number<u8> = 0x0F
either_open <- open_paths.bitwise_and(north_and_south) != 0
System.screen.border <- if either_open then .green else .red end

A number literal itself is always positive: -5 is the unary - operator applied to 5. If a number is mistyped—say, trailing letters after digits, a 0x or 0b prefix with no digits, a leading or trailing underscore, or two underscores side by side—the compiler flags it with badNumber.

Decimal Literals

A decimal literal has digits on both sides of a decimal point, like 0.5 or 3.25. It holds its exact mathematical value until it lands in a destination type, which then snaps it to the nearest fixed-point step of 1/256. Writing a decimal point always marks the literal as fractional, even when the fraction part is zero—so 2.0 asks for a fractional type while 2 stays a whole number.

decimal-literal ::= decimal-digits '.' decimal-digits

Handing a decimal literal to a whole-number type won't slip past the compiler; use a whole number or an explicit rounding call instead.

String Literals

A string literal is a row of printable ASCII characters—from space ( ) through tilde (~)—wrapped in double quotes on a single line. Inside the quotes, \" produces a literal double quote and \\ produces a literal backslash; those are the only two escape pairs you ever need to remember.

string-literal   ::= '"' string-character* '"'
string-character ::= any printable ASCII character except '"' and '\'
                   | '\"' | '\\'

Under the hood, a string literal is simply a fixed-length list of Char, one per character: "HELLO" has the type [5 of Char]. Wrapping it in ScreenCode("HELLO") translates those characters straight into screen codes ready for the display, as Types shows.

const greeting = "SAY \"HI\""
System.screen.text[0][0..<8] <- greeting

The compiler keeps strings crisp and predictable: it catches characters outside printable ASCII (such as accented letters) with stringNotPrintable, a string that runs off the end of its line without a closing quote with unterminatedString, and any unknown backslash escape with badEscape.

Yes-or-No and Missing Values

true and false are the two values of the boolean type bool. nil stands for the missing value of any optional type.

Operators and Punctuation

These symbol tokens glue expressions and declarations together. The Expressions chapter shows what each operator computes and the precedence order in which they bind.

operator    ::= '+' | '-' | '*' | '/' | '%' | '+%' | '-%' | '+|' | '-|'
              | '==' | '!=' | '<' | '<=' | '>' | '>=' | '??' | '++' | '...' | '..<'
punctuation ::= '=' | '<-' | ':' | '->' | '?' | '(' | ')' | '[' | ']' | ',' | '.'

Types

Every value in an Adder program has a type, and the compiler knows every type before a single instruction runs. A type tells the machine which values a name can hold and how many precious bytes of memory to set aside for it. Values never silently morph from one type into another behind your back—Adder converts a value only where your program writes the conversion out in the open. If a value of the wrong type is handed to a spot that expects something else, the compiler catches the mismatch right away with wrongType.

Here is the full cast of types you can work with:

• numbers, defined by the exact range of values each one holds;
• yes-or-no values, of type bool;
• named sets built into the machine, such as Color, Note and Key;
• characters and screen codes for text and screen cells;
• pictures and fonts, which the compiler packs straight into your program;
• enums and structs, either declared by your program or built in;
• lists of a fixed length;
• optionals, which hold either a value or nil;
• events, which happen at specific moments rather than sitting in memory.

type          ::= number-type | name type-range? | list-type | type '?'
                | 'Event' ( 'of' type )? | 'Result' 'of' type
number-type   ::= 'Number' ( '<' format-name '>' | '<' range '>' )?
range         ::= bound '...' bound | bound '..<' bound
type-range    ::= '<' bound '...' bound '>'
list-type     ::= '[' size 'of' type ']'

Numbers

In Adder, a number type is simply the range of values you need it to hold. Number<low...high> holds every value from low through high, including both ends. Number<low..<high> holds every value from low up to, but stopping just short of, high—handy when counting across 40 columns numbered 0 through 39.

var lives: Number<0...3> = 3
var column: Number<0..<40> = 0
when System.keyboard.space.pressed
  lives = lives -| 1
  column = column +% 1
end
System.screen.text[0][0..<1] <- lives.digits(1)
System.screen.border <- Color(column % 16)

Range Bounds

Both ends of a range must be fixed values that the compiler can work out before the program runs. An end can be a literal number, a numeric constant declared earlier, a bound member of a numeric type like Lane.last, a unary minus, or a compile-time calculation built from those using +, -, *, / and %. Whenever an end is a calculation, wrap it in parentheses so the angle brackets stay easy to read. Each bound expression can have at most 128 parts and nest up to 32 levels deep.

const columns = 40
type Column = Number<0..<(columns * 2)>
var column: Column = 0
System.screen.border <- Color(column % 16)

Because a variable, a binding, a live device reading or a function call only gets its value while the program is running, none of them can serve as a range bound (rangeEndNotFixed).

Likewise, a range whose starting value is greater than its ending value has no room for any number at all, so the compiler flags it with rangeEmpty.

Fractions

Write a decimal point in either end of a range and you get a fixed-point fractional type, measured in crisp steps of 1/256. Number<0.0...1.0> holds 0, 1/256, 2/256 and so on all the way up to 1—smooth enough for sub-pixel sprite motion and gentle gravity curves without floating-point overhead. In a fractional range, ..< leaves out just the final 1/256 step: Number<0.0..<1.0> tops out at 255/256 (about 0.996).

When a fractional type receives a decimal literal, it snaps the number to the nearest 1/256 step; if that rounding nudges a literal past either end of the range, the compiler lets you know.

A whole number fits naturally into a fractional spot without a conversion whenever its range fits inside. Going the other way—turning a fraction back into a whole number—always asks you to pick how to round it with floor(), round() or ceil(), as Expressions describes.

Storage Formats

The compiler packs each number into the smallest of eight formats that can hold its entire range. If you want the full span of a machine format, you can write the format name itself inside Number<...> instead of a range.

Even when a narrow range rides inside a 1-byte format, it remembers its own exact bounds: Number<0...9> takes one byte in memory and still accepts only 0 through 9. If a range stretches wider than every available format—such as -1 to 65,535, which needs both negative numbers and the top half of a 16-bit unsigned word—the compiler stops with rangeNoRepresentation, and any unknown format name inside Number<...> triggers numericFormat.

Individual bit positions belong to the two unsigned formats: Number<u8> gives you 8 bits and Number<u16> gives you 16, ready for the bit operations in Expressions to inspect and flip. If you have a ranged number or a default Number and want to twiddle its bits, convert it to Number<u8> or Number<u16> first.

The Default Number

Written by itself, Number holds whole numbers from -32,768 to 32,767—the full span of i16. When you declare a var without spelling out its type, it takes that i16 range if its starting value is a whole number, or the i16.8 range if its starting value has a decimal point. Starting a variable at a small number never boxes it in: var score = 0 has plenty of headroom to climb to 30,000 later on.

var score = 0
var speed = 0.5
fn apart(a: Number, b: Number): Number
  if a > b then a - b else b - a end
end
System.screen.text[0][0..<3] <- apart(score, 100).digits(3)

A <- binding automatically takes the tightest range the compiler can prove for its expression, while a constant keeps its exact single value.

Values Outside a Range

Whenever the compiler can see right away that a value falls outside its target range, it catches the mistake at compile time.

Of course, variables change as the game plays, and the compiler cannot always prove ahead of time that a calculation stays in bounds. When a runtime check is needed, the compiled program guards the store automatically: if an out-of-range number tries to slip in, the program halts cleanly and prints the offending line number right on the screen. When you want a number to loop around or stop at the ends—like a color cycling from 15 back to 0 or a life counter stopping at 0—reach for the wrapping (+%, -%) or clamping (+|, -|) operators described in Expressions.

Type Aliases

type Name = T gives an existing type a clear, domain-specific name of your choosing. An alias does not wall off a separate type: values of the alias and values of T work together seamlessly, while compiler messages kindly use your alias name. For any numeric alias, .first and .last give you its lower and upper bounds by name.

type Lane = Number<0...39>
fn mirror(x: Lane): Lane
  Lane.last - x
end
column: Lane <- System.screen.frame.cycle()
System.screen.text[0][0..<2] <- mirror(column).digits(2)

Yes-or-No Values

The boolean type bool has just two values—true and false—and takes a single byte. You can combine boolean values with and, or and not. Adder never guesses whether a number or an optional means true or false, so the compiler won't let either one stand in for a bool condition.

var paused: bool = false
when System.keyboard.p.pressed
  paused = not paused
end
System.screen.border <- if paused then .red else .black end

Named Sets

The machine's own palettes, musical notes, keys and settings are represented as named sets: each item has both a readable name and an underlying number, and each takes one byte. You can write a value in full, like Color.red, or use the short dotted form .red wherever the expected type is already clear from context. Inside a match on a named set, each pattern is written as the bare name without a leading dot.

The 64 Key names are delete, return, cursor_right, f7, f1, f3, f5, cursor_down, three, w, a, four, z, s, e, left_shift, five, r, d, six, c, f, t, x, seven, y, g, eight, b, h, u, v, nine, i, j, zero, m, k, o, n, plus, p, l, minus, period, colon, at_sign, comma, pound, asterisk, semicolon, home, right_shift, equals, up_arrow, slash, one, left_arrow, control, two, space, commodore, q and run_stop.

Calling the type's name like a function converts a number into a member of that set: Color(n) picks color number n, and Attack(2) sets a voice attack rate of 2. If a fixed number falls outside the set's valid range, the compiler catches it with conversionOutOfRange; if the number can change while the program runs, the program checks it on the spot.

var hue: Number<0...15> = 0
when System.keyboard.space.pressed
  hue = hue +% 1
end
System.screen.border <- Color(hue)
System.screen.background <- Color.random()

Narrowed Named Sets

Just like numbers, a named set can be narrowed to a contiguous slice of its values by writing a range in angle brackets after the type name, with both ends included. Note<Note.c3...Note.c5> holds only the two octaves from c3 through c5, and a type alias makes a narrowed set effortless to reuse.

type Melody = Note<Note.c3...Note.c5>
var note: Melody = .c4
when System.keyboard.space.pressed
  note = if note == Note.c5 then Note.c3 else Note.c4 end
end

Characters and Screen Codes

A Char represents a single character of text, numbered 0 to 127 in standard ASCII order: Char(65) is A, and Char.space is a blank space. Every string literal you write is a fixed-length list of Char.

A ScreenCode, numbered 0 to 255, is the byte that actually sits in a cell of the text screen to pick one glyph from the active 256-character font. ScreenCode.space is the blank cell and ScreenCode.block is the solid filled block. Calling ScreenCode(text) converts a whole string into the screen codes that display it, while ScreenCode(c) converts a single Char.

const sign = ScreenCode("ADDER")
var shown: Char = .space
when s = System.keyboard.stroke
  if c = s.character() then
    shown = c
  end
end
System.screen.text[0][0..<5] <- sign
System.screen.text[12][20] <- shown

Pictures and Fonts

Adder lets you draw sprites, custom characters and bitmap art right in your source file as visual grids of text, which the compiler bakes directly into your compiled program. These art values are constants, usually built from lists of strings where . leaves a pixel clear and X lights it up. A program can pack up to 256 distinct values of each art type.

When you draw a multicolor Shape or Picture, each pixel is twice as wide and chooses from four palette slots written ., A, X and B. Charset(glyphs, map:) builds a complete font from a list of 256 glyphs, with an optional map: of 128 screen codes that tells the machine which glyph each Char displays. Charset(file:) loads a raw 2,048-byte character set file straight from your project folder. See The System Device Tree for how to put your shapes, fonts and pictures up on the screen.

const ship = Shape([
  "....AAAA....", "...AXXXXA...", "..AXXXXXXA..", ".AXXBBBBXXA.", "AXXBBBBBBXXA", "AXXBBBBBBXXA", ".AXXBBBBXXA.",
  "..AXXXXXXA..", "...AXXXXA...", "....AAAA....", "............", "............", "............", "............",
  "............", "............", "............", "............", "............", "............", "............"
])
System.screen.sprite[0] <- (x: 100, y: 100, shape: ship)

If a row of pixel characters is the wrong width or contains an unrecognized character, the compiler points out the exact row with pixelAsset.

Enums

An enum defines a brand-new type whose values are a hand-picked list of named cases—ideal for game states, directions or monster behaviors. Every enum name starts with a capital letter.

enum Mode
  case title, playing, over
end
var mode: Mode = .title
when System.joystick[2].fire.pressed
  mode = mode.next()
end
System.screen.border <- match mode
  title -> .blue
  playing -> .black
  over -> .red
end

When an enum's cases carry no extra fields, they stay in the order you listed them: < and > compare them by position, Mode.first and Mode.last give the two ends, and .next() steps forward from case to case, wrapping neatly from the last back to the first. A simple enum like this takes just one byte.

Cases can also carry named fields of their own. You build such a case by labeling its fields, and unpack those fields inside a match arm:

struct Spot(x: Number<0...319>, y: Number<0...199>)
enum Drag
  case still
  case moving(grab: Spot, column: Number<0...39>)
end
var drag: Drag = .still
var column: Number<0...39> = 0
when System.joystick[2].fire.pressed
  drag = .moving(grab: (x: 10, y: 20), column: 4)
end
when System.screen.frame
  match drag
    moving(grab, column: chosen) ->
      column = chosen
    still ->
  end
end

An enum with fields takes one byte for its case tag plus enough bytes to hold the fields of its largest case.

enum-declaration ::= 'enum' name newline case-line+ 'end'
case-line        ::= 'case' enum-case ( ',' enum-case )* newline
enum-case        ::= name ( '(' field ( ',' field )* ')' )?
field            ::= name ':' type

Structs

A struct bundles related named fields into a single tidy value—like a sprite's velocity, an enemy's coordinates or a high-score row. In its compact one-line form, you list the fields inside parentheses right after the struct's name. Any field can specify a default value with =, which steps in whenever a newly created struct value leaves that field out.

struct Speed(x: Number<-3...3>, y: Number<-3...3> = 0)
const speeds: [3 of Speed] = [(x: 1, y: 2), Speed(x: -1, y: 3), (x: 2)]
n: Number<0..<3> <- System.screen.frame.every(30).cycle()
s <- speeds[n]
System.screen.sprite[0] <- (x: 100 + s.x * 10, y: 100 + s.y * 10)

When you create a struct value, you label each field you supply. You can write the type name out in front, like Speed(x: 1, y: 2), or write just (x: 1, y: 2) whenever the receiving spot already expects a Speed. A spot knows what struct type to expect when it is a typed var, a function parameter, a function's return value, a struct or enum field, an element of a typed list, a branch of an if or match, or a hardware sprite output. That expected type also flows right through an optional (Speed?), into a single value replicated across a whole list ([4 of Speed] = (x: 0, y: 0)), and into the body of a .map(...) arrow whose result is expected to be a list of structs. If you write an unnamed (x: 1, y: 2) where no struct type is expected, the compiler flags it with structNeedsContext, quotes the value back to you, and—when only one struct in your program has those field names—shows the exact named form to use. Reading a field is as simple as value.field, and a struct takes the sum of its fields' bytes in memory.

For richer types, the multi-line block form of struct can also hold mutable var fields and member functions (fn and op), as Declarations explains. To keep structs self-contained, a struct's function reads only its parameters, the struct's own fields and the program's top-level constants; if it needs a program variable, binding or hardware device, pass that value in as an argument rather than reading it directly (operationScope).

struct-declaration ::= 'struct' name '(' struct-field ( ',' struct-field )* ')'
                     | 'struct' name newline struct-member* 'end'
struct-field       ::= name ':' type ( '=' expression )?

Built-In Structs

A sprite's x and y coordinates measure pixels from the top-left corner of the visible picture, and their negative lower bounds let a sprite glide smoothly onto and off every edge of the screen.

Lists

[n of T] is a fixed-length list holding n items of type T. Because small machines thrive on predictable memory layout, the length n is a whole number from 1 to 65,535 known at compile time (and may be a parenthesized calculation of constants). Elements can be of any type, including inner lists: [3 of [4 of Number<u8>]] gives you a neat 3-by-4 grid.

const rows = 3
var grid: [rows of [4 of Number<u8>]] = 0
const tune: [4 of Note?] = [.c4, nil, .e4, .g4]
when System.keyboard.space.pressed
  grid[1][2] = 7
end
System.screen.text[0][0..<1] <- grid[1][2].digits(1)

In memory, a list takes n times the byte size of a single element. Handing a single element value to a whole list fills every slot with that value—just as = 0 zeroes out every cell of grid above. The ++ operator splices two lists together as long as both lengths are known at compile time, even if their elements change while the program runs; the combined list has the sum of their lengths and a single shared element type:

const base = [1, 2, 3]
var extra: [2 of Number<u8>] = [7, 8]
joined <- base ++ extra
System.screen.border <- Color(joined[4] % 16)

If a list's length falls outside 1 to 65,535, the compiler catches it with arraySize.

You can also write functions that accept a list of any length by using single-letter names for the length and element type in the parameter list, as Declarations shows:

fn keep(values: [n of T]): [n of T]
  values
end
const numbers = keep([1, 2, 3])
const flags = keep([true, false])

Turn to Expressions to see how to index a single element, slice a window of consecutive elements, or carve out a rectangular patch from a 2D grid.

Optionals

Adding a question mark to any type—T?—makes it optional: it holds either a present value of type T or the missing value nil. In memory, T? takes just one extra byte beyond T to track whether a value is there.

var held: Number<u8>? = nil
when System.keyboard.space.pressed
  held = 7
end
when System.keyboard.delete.pressed
  if n = held then
    held = n -| 1
  end
end
shown <- held ?? 0
System.screen.border <- if held != nil then Color(shown % 16) else .black end

You have three clean ways to work with an optional value:

• value ?? fallback unwraps the value when present, or hands back fallback when it is nil;
• value != nil and value == nil test whether a value is currently there;
• if name = value then, guard name = value and when name = event unwrap the value into name for the body block whenever it is present.

An optional is never a boolean condition on its own, so writing if held then triggers bareOptional. Checking flares[i] != nil also proves to the compiler that flares[i] holds a real value inside the then branch (and on the right-hand side of and), allowing you to call mutating operations directly on flares[i] there. Likewise, flares[i] == nil proves the value is present inside the else branch, and guard flares[i] != nil proves it for the remainder of the handler.

Events

An event—like System.keyboard.space.pressed or System.screen.frame—represents a moment in time rather than a stored value in memory. Some events fire as a pure pulse (Event), while others carry a fresh payload each time they happen (Event of T), such as System.keyboard.stroke carrying a Keystroke.

press: Event <- System.joystick[2].fire.pressed
stroke: Event of Keystroke <- System.keyboard.stroke
var presses: Number<0...9> = 0
when press
  presses = presses +% 1
end
System.screen.text[0][0..<1] <- presses.digits(1)

Because an event happens at moments rather than sitting in RAM, you can give it a name with a <- binding, whereas trying to store an event in a constant or a var triggers eventConstant. The Events and Handlers chapter shows all the ways your program can listen, filter and respond to events.

Results

When background work talks to an external device like a disk drive, the operation finishes either with the data you asked for or with a report of what went wrong. Result of T is a built-in enum with two cases: success(value: T) and failure(reason: Failure). Failure is itself an enum with the cases not_present and device_error(code:), where code is a Number<u8>.

const reading: Result of Number<u8> = .success(value: 3)
System.screen.border <- match reading
  success(value) -> Color(value)
  failure -> .red
end

Expressions

Whenever your program adds two scores, checks whether a sprite has reached the edge of the screen, or picks a fresh border color, it uses an expression. An expression is any formula or recipe that works out a value.

Before your program ever starts up, the compiler looks over every expression you write. It knows the exact type of every part, and for numbers it also tracks the lowest and highest values the calculation could possibly reach. If two parts do not belong together—say, trying to add a color to a number—the compiler catches the mix-up right away so you can fix it before running.

expression      ::= unary ( binary-operator unary )*
unary           ::= ( '-' | 'not' ) unary | postfix
postfix         ::= primary selection*
selection       ::= '.' name ( '(' arguments? ')' )?
                  | '[' expression ( ',' expression )? ']'
primary         ::= literal | name | '.' name | name '(' arguments? ')'
                  | number-type '(' arguments ')' | 'start'
                  | '(' expression ')' | list-value | struct-value
                  | if-value | match-value
binary-operator ::= 'when' | 'or' | 'and'
                  | '==' | '!=' | '<' | '<=' | '>' | '>='
                  | '??' | '...' | '..<'
                  | '+' | '-' | '+%' | '-%' | '+|' | '-|' | '++'
                  | '*' | '/' | '%'

Operators and Their Order

When you string several operators together in one expression, Adder needs to know which ones bind first—just like multiplication comes before addition in everyday math. The table below lists all the operators from the tightest grip at the top to the loosest at the bottom. Operators sitting on the same row have equal strength and work from left to right.

Because of this order, -a * 2 means (-a) * 2, a + b * 2 means a + (b * 2), and not a == b means not (a == b). Whenever you want a different order—or just want to make your intent unmistakable at a glance—wrap that part in parentheses (...) so it runs first.

var a: Number<0...9> = 2
var b: Number<0...9> = 3
var paused: bool = false
result <- a + b * 2                     // 8
grouped <- (a + b) * 2                  // 10
moving <- not paused and a != b         // (not paused) and (a != b)
System.screen.border <- if moving then Color(result) else Color(grouped % 16) end

Two small combinations ask you to spell out what you mean:

• Comparisons do not chain together in a row. Writing a < b < c raises chainedComparison; spell out both halves as a < b and b < c.
• A range (... or ..<) and the ?? fallback operator do not mix naked in the same expression. The compiler flags that with parenthesize and asks you to add parentheses around whichever part should happen first.

Arithmetic

The five classic math operators—+, -, *, / and %—work on any two numbers. You can freely mix numbers of different storage formats, and if you combine a whole number with a fraction, the result becomes a fraction so nothing after the point is lost. If you accidentally hand an arithmetic operator something that is not a number, such as a Color or a bool, the compiler stops and lets you know.

Results and Their Ranges

One of Adder's friendliest tricks is that intermediate math inside an expression does not silently wrap around behind your back. Instead, the compiler works out the true range of each step from the ranges of the numbers going in. If a and b can each hold 0 through 9, then a + b spans 0 to 18, a - b spans -9 to 9, and a * b spans 0 to 81. It even notices when a number is multiplied by itself: a * a is a square, so its range never dips below zero! Adder then picks the smallest storage format that fits that full range, keeping the calculation itself safe from overflow.

var side: Number<1...20> = 1
area <- side * side                     // 1 to 400, in two bytes
when System.keyboard.space.pressed
  side = side +% 1
end
System.screen.text[0][0..<3] <- area.digits(3)

If an expression grows so wide that no storage format in the machine can hold its range—for instance, adding two full-range Number<u16> values in a binding—the compiler flags rangeNoRepresentation, points out the widest operand, and suggests giving it a tighter range.

The default number plays by a slightly different rule. Whenever either side of an operation is a plain, unannotated Number, the result is also a default Number spanning -32,768 to 32,767, and the program checks every step as it runs. Keep this in mind for formulas like (x + y) / 2: if x and y are default numbers holding 30,000, the addition itself steps past 32,767 and halts the program before / 2 gets a chance to bring the answer back down.

When an arithmetic expression is made entirely of constants, the compiler does the math at compile time and bakes in the exact answer.

Checked Arithmetic

What happens when a calculation finishes and you store the answer into a place with a specific range—a variable, a struct field, a function parameter, a list element, or a typed binding? There are three cases:

1. Guaranteed to fit: When the compiler can prove from the ranges that the result always fits, it emits no runtime check at all—your code runs at full speed.
2. Guaranteed to miss: When the compiler can see that the answer can never fit, it catches the mistake right away with literalDoesNotFit for a constant or rangeExceeded for a calculation.
3. Might or might not fit: When the expression's possible range is wider than the destination, Adder inserts a safety check each time the value is stored. If a number steps out of bounds while you play, the program halts cleanly and prints the offending line on the screen instead of corrupting your game state.

var lives: Number<0...3> = 3
when System.keyboard.space.pressed
  lives = lives - 1                     // the fourth press stops the program here
end
System.screen.text[0][0..<1] <- lives.digits(1)

Even better, testing a number in an if condition narrows its known range inside the branch! Inside if lives > 0 then, the compiler knows lives is at least 1, so lives - 1 is guaranteed to stay within 0...2 and needs no runtime check at all. Any check that does stay in the program takes a handful of bytes and cycles, which you can inspect anytime in the cost report.

Wrapping and Clamping

In arcade games and demos, you often want a counter to loop smoothly back to the start or stop cleanly at a wall without writing an if statement. Adder gives you dedicated operators for both:

• +% and -% wrap: step past one end of the range and you come right back in from the other end, like a color wheel or an asteroid drifting across the screen edge.
• +| and -| clamp: step past one end of the range and you stop right at the boundary, like a paddle hitting the wall or a volume knob turned all the way up.

Neither wrapping nor clamping ever halts your program.

Both pairs use the declared range of the destination receiving the value—whether that is a variable, a list element, a field, a parameter, or a typed binding. They follow your logical range rather than the underlying byte size, so a Number<0...9> wraps cleanly from 9 back to 0, not at 255. Because they need a target range to know where the ends are, using them in a place that declares no range—such as an untyped binding or inside a conversion like Color(...)—triggers operationNeedsRange.

var hue: Number<0...15> = 0
var level: Number<0.0...1.0> = 0
when System.screen.frame
  hue = hue +% 1                        // 15 wraps to 0
  level = level +| 0.125                // stays at 1.0
end
System.screen.border <- Color(hue)

Musical notes have a fixed keyboard span and do not wrap around from top to bottom, so using +% or -% on a Note raises noteWrap. You can still add or subtract a whole number from a Note (or clamp with +| and -|) to shift it by that many semitones, and subtracting one Note from another gives you the distance between them in semitones.

Division and Remainder

/ divides two numbers and drops any remainder toward zero: 7 / 2 gives 3, and -7 / 2 gives -3. % gives the remainder left over after division, keeping the sign of the left-hand number: 7 % 3 is 1, and -7 % 3 is -1.

Dividing by a constant zero is caught immediately with divisionByZero. If the divisor is a variable or expression that could become zero while the program runs, Adder checks it before dividing and halts on that line if zero ever shows up.

Fractions

A fractional number measures values in fine steps of 1/256. Adding and subtracting fractions is completely exact. Multiplying or dividing fractions works out the answer in steps of 1/256 and drops any leftover sub-step toward zero.

Conversions

Adder never turns one type into another behind your back. When you want to convert a number into a narrower range, turn a color into its palette number, or round a smooth fraction down to a pixel column, you write that step right in your code.

Number Conversions

Use any number type as if it were a function to convert a value into that type. Writing Number<u8>(v), Number<0...15>(v), or Number(v) gives you v expressed in that target type.

var wide: Number<0...300> = 0
var shade: Color = .red
byte <- Number<u8>(wide)                // checked: stops above 255
nibble <- Number<0...15>(byte)
code <- Number<u8>(shade)               // a color's number, 2 for red
System.screen.border <- Color(nibble)
System.screen.text[0][0..<3] <- code.digits(3)

If the compiler cannot prove at compile time that v always fits inside the target range, the conversion checks it at runtime. If the compiler can see that v definitely lies outside the target range, it points that out immediately with conversionOutOfRange. And if you try to pass a fractional number directly into a whole-number type, it stops with conversionDropsFraction so you can choose how you want to round it.

Going the other way—placing a whole number into a fractional type—needs no conversion at all as long as its range fits. To turn a fraction into a whole number, pick one of the three rounding functions below.

The machine's built-in named sets convert from numbers using their own type names in the very same style, such as Color(n) or Char(65).

Dropping a Fraction

When a sprite's smooth fractional position needs to snap to a character cell or pixel coordinate, call floor(), round(), or ceil() to turn the fraction into a whole number:

The compiler rounds the ends of the number's range the exact same way, so round() on a Number<-2.5...2.5> produces a whole number with range -2...3. Calling any of the three on a number that is already whole simply returns it unchanged.

var x: Number<0.0...39.75> = 0
column <- x.floor()
nearest <- x.round()
when System.screen.frame
  x = x +% 0.25
end
System.screen.text[0][column] <- ScreenCode.block
System.screen.text[1][0..<2] <- nearest.digits(2)

Other Number Functions

Every number also responds to a handy set of built-in helpers:

n.clamp(lo...hi) and n.wrap(lo...hi) bound a whole number right inside an expression and narrow its type to that exact range, so (x + dx).clamp(24...320) or (frame + offset).wrap(0..<8) flows straight into a sprite coordinate or list index without a separate variable. n.digits(k) is the classic way to print a live score or timer onto the screen: it turns n into a [k of Char] padded with leading zeros (like "0042" for 4 digits), checking at runtime that n is between 0 and the largest k-digit number. If you want to call a dot-function directly on a number literal, wrap the number in parentheses first—write (15).sqrt() rather than 15.sqrt(), which the compiler flags with numberMember because the dot looks like a decimal point.

Bit Operations

Under the hood, a Number<u8> is a neat row of 8 switches (bits 0 through 7, counting from the right) and a Number<u16> is a row of 16 (0 through 15). Packing flags, dungeon doors, or bitmasks into a single byte is a beloved 8-bit craft, and Adder gives you clear, readable functions to inspect and flip those bits. Every bit function returns a fresh value and leaves the original number untouched.

A bit position or shift count runs from 0 to 7 on a Number<u8>, and from 0 to 15 on a Number<u16>. Better yet, you can pass a case from a fieldless enum as a bit position—Adder uses its position in the enum's declaration (0, 1, 2, ...), giving your bit flags self-documenting names! Bits shifted past either end of the number simply drop off, so Number<u8>(0x81).shift_left(1) becomes 2. Any mask you pass to bitwise_and, bitwise_or, or bitwise_xor must fit within the receiver's 8-bit or 16-bit width.

enum Path
  case north, east, south, west
end
var open_paths: Number<u8> = 0b0000_0101
north_open <- open_paths.bit_is_set(.north)
either <- open_paths.bitwise_and(0x05) != 0
when System.keyboard.e.pressed
  open_paths = open_paths.toggle_bit(.east)
end
System.screen.border <- if north_open and either then .green else .red end

Bit operations only work on exact 8-bit or 16-bit unsigned values (Number<u8> or Number<u16>). Calling them on any other number triggers bitwiseReceiver—just convert the number to Number<u8> or Number<u16> first. If a constant bit position, shift count, or mask steps outside the width of the number, the compiler catches it with bitwiseArgument; if the position or count changes while the program runs, Adder checks it on the spot.

Comparisons and Yes-or-No Values

Comparisons

The six comparison operators—==, !=, <, <=, > and >=—compare two values and hand back a bool (true or false). You can compare any two values that share the same kind:

• any two numbers, regardless of their ranges or storage formats;
• two values from the same named set, such as two Color values or two Char values;
• two cases from the same enum.

The ordering operators (<, <=, > and >=) compare numbers by their value, named sets by their underlying machine numbers, and fieldless enums by the order their cases appear in the enum declaration. Two bool values can be tested for equality with == and !=. Structs cannot be compared directly; trying to compare structs or mismatched types triggers cannotCombine.

What if you compare two lists, or a list against a single value? Adder compares them element by element and hands you back a list of bool values, as Operations Over Lists explains.

and, or and not

and, or and not combine and flip bool values. Both and and or are short-circuiting, meaning they stop as soon as the outcome is settled: in a and b, if a is already false, Adder skips working out b. These operators want real yes-or-no values, not numbers: handing a number to not triggers notNeedsBool, and handing a number to and or or triggers needsBooleans.

You can also use and and or to combine events, as shown in Events and Handlers.

Optionals and ??

Because an optional (T?) might hold nil, you can compare it with == and != against nil or against another optional of the same type. Comparing an optional directly to a plain, non-optional value raises optionalCompare.

When you want to unwrap an optional and supply a default whenever it is empty, reach for the ?? fallback operator: value ?? fallback gives you the value inside the optional when one is present, or fallback when the optional is nil. Because fallback is a plain value of the inner type, the result of value ?? fallback is guaranteed never to be nil. Using ?? on a value that is not optional in the first place triggers coalesceNeedsOptional.

var held: Number<u8>? = nil
var other: Number<u8>? = 5
same <- held == other
present <- held != nil
shown <- held ?? 0
when System.keyboard.space.pressed
  held = 7
end
System.screen.border <- if same or present then Color(shown % 16) else .black end

An optional is not itself a bool, so writing if held then triggers bareOptional—write if held != nil then (or unwrap it with if v = held then in a statement) instead.

Lists

List Values

Write a list by placing its elements inside square brackets, separated by commas: [2, 3, 5, 7]. For a list of numbers, the element type spans from the smallest number in the list to the largest; for other values, the list takes the type of its first element. When you store the list into a place that already declares a list type, every element takes that declared element type instead. Every list in Adder has a fixed, non-zero size: an empty [] is flagged with emptyArray, and a list whose length does not match its destination is flagged with wrongLength.

list-value   ::= '[' ( expression ( ',' expression )* ','? )? ']'
struct-value ::= '(' name ':' expression ( ',' name ':' expression )* ','? ')'

Two handy shorthands also build lists for you:

• A range used as a value, such as 0..<4, expands into the list of numbers it spans: [0, 1, 2, 3].
• A string literal like "HI" is a list of Char.

A struct value, written in parentheses with labeled fields like (x: 10, y: 20), is described in Structs.

const primes = [2, 3, 5, 7]                   // four numbers, each from 2 to 7
const tune: [3 of Note] = [.c4, .e4, .g4]
steps <- 0..<4
System.screen.border <- Color(primes[1] + steps[2])

Indexes

Write xs[i] to pick out element i of xs, counting from 0 at the front. The index must be a whole number: passing a fraction triggers indexNotInteger, and passing a constant index outside the list's bounds triggers indexOutOfBounds. When i changes at runtime and its range could step outside the list, Adder checks i before touching memory and stops cleanly on that line if it goes out of bounds.

For quick access to the ends of a list, xs.first and xs.last give you the first and last elements without counting. A two-dimensional grid is simply a list of row lists, so grid[row][col] picks out one cell from one row. And if you have a list of structs, asking for a field gives you a list of that field across every element: corners.x gives you the list of every corner's x coordinate.

const grid = [[1, 2, 3], [4, 5, 6]]
var row: Number<0...1> = 0
var col: Number<0...5> = 0
corner <- grid[row][2]
when System.keyboard.space.pressed
  row = row +% 1
  col = col +% 1
end
System.screen.border <- Color(corner + grid.last.first)
System.screen.background <- Color([1, 2, 3, 4][col % 4])

Windows

Instead of a single index, you can put a range inside the brackets to look through a window of consecutive places in a list—perfect for scrolling a banner across the screen or updating a group of columns at once! For example, xs[2..<6] is a window of four elements starting at index 2.

Every window has a fixed length known at compile time, even when its starting index moves from frame to frame. When the start is a constant, the end is a constant too (xs[2..<6]); when the start is a changing expression a, write the end as a plus a constant offset, such as xs[a..<(a + 4)] or xs[a...(a + 3)]. If the compiler cannot tell the window's fixed length, it flags sliceLengthUnknown; if a constant window reaches past the end of the list, it flags sliceOutOfBounds. When a sliding window's start could step past the list at runtime, Adder checks the start index once when the window is formed.

const sign = ScreenCode("          ADDER SCROLLS A LONG SIGN ACROSS THE TOP ROW          ")
left: Number<0...20> <- System.screen.frame.every(8).cycle()
System.screen.text[0] <- sign[left..<(left + 40)]

A window is a live view, not a copy: reading from a window reads the underlying list in place, and passing a window to a function lets the function read those elements right where they sit. Even better, if you bind a name to a window of a variable list (window <- items[i..<(i + 4)]), that binding takes zero bytes of storage and points straight at those slots—so a handler that writes to window writes directly into items! (Trying to write through a window of a constant list is caught with sliceBindingWrite.) If you initialize a var from a window, that variable makes its own separate copy of the elements. See Statements for more on writing into windows.

Rectangles

On a two-dimensional list of rows, you can slice both directions at once by placing two ranges inside the brackets, separated by a comma—rows first, then columns. grid[r..<(r + 2), 1..<3] carves out a 2-by-2 rectangle: a list of two rows, where each row is a two-element window. Both ranges follow the same fixed-length window rules above. Because a rectangle index always slices both dimensions, both parts inside [..., ...] must be ranges; if either one is a single index, the compiler flags rectangleRanges—to take a window of a single row, index the row first and then slice it, as in grid[r][1..<3].

const grid = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
var top: Number<0...1> = 0
corner <- grid[top..<(top + 2), 1..<3]  // two rows of two numbers
when System.keyboard.space.pressed
  top = top +% 1
end
System.screen.border <- Color(corner[1][1])

Joining Lists

The ++ operator joins two lists end to end: a ++ b contains all the elements of a followed immediately by all the elements of b. Both lists must share the same element type (or both be lists of numbers), and their combined length can be up to 65,535 elements. To keep memory layout simple and predictable, each side of ++ must be a list literal, a named list, a struct member, or an indexed element; if you try to join the result of a function call directly, the compiler flags joinLists—just bind that call to a name on the line above first.

const low = [1, 2, 3]
var high: [2 of Number<u8>] = [7, 8]
all_of <- low ++ high                   // [5 of Number<u8>]
System.screen.border <- Color(all_of[4] % 16)

Value if and match

In Adder, if and match are not just for running statements in handlers—they can also be used right inside an expression to pick a value! Only the branch or arm that wins is worked out; the others are skipped.

if-value    ::= 'if' expression 'then' value-body
                ( 'else' 'if' expression 'then' value-body )* 'else' value-body 'end'
value-body  ::= expression | newline ( name '=' expression newline )* expression newline
match-value ::= 'match' expression newline value-arm+ 'end'
              | 'match' newline condition-arm+ 'else' '->' expression newline 'end'
value-arm   ::= pattern ( 'when' expression )? '->' expression newline
              | 'else' '->' expression newline
condition-arm ::= 'when' expression '->' expression newline
pattern     ::= name | '-'? whole-literal | 'true' | 'false' | 'nil'
              | name '(' field-pattern ( ',' field-pattern )* ')'
field-pattern ::= name ( ':' name )?

if

Because an expression must always produce a value, a value if always needs an else branch; leaving else off triggers valueIfElse. The condition after if can be any bool expression, or an event (which counts as true during any frame in which that event fires). You can chain additional tests with else if on the same line, closing the whole chain with a single end.

Each branch can be a compact one-liner or span several lines: when a branch spans multiple lines, you can define local helper constants with const on the opening lines, and the final line of the branch becomes its resulting value. Inside the then branch, Adder knows the condition is true and narrows your number ranges accordingly—so in if a > 3 then a - 4 else 0 end, the compiler knows a is at least 4 in the first branch and proves that a - 4 never drops below 0.

All branches of a value if must agree on the type of value they return (mixing types raises wrongType). When the branches return numbers, the overall range of the if expression spans from the lowest minimum of any branch to the highest maximum of any branch.

var a: Number<0...9> = 0
lift <- if a > 3 then a - 4 else 0 end  // 0 to 5
shade <- if a == 0 then Color.red else if a < 5 then .yellow else .green end
scaled <- if a > 5 then
  const over = a - 5
  over * 3
else
  0
end
when System.keyboard.space.pressed
  a = a +% 1
end
System.screen.border <- shade
System.screen.text[0][0..<2] <- (lift + scaled).digits(2)

match on a Value

When you are choosing between several cases—like game states, directions, or specific numbers—match value inspects the value from top to bottom, picks the first arm whose pattern matches, and returns the expression after ->.

You can refine any pattern by adding when condition before the ->; that arm then matches only when both the pattern and the condition hold, and the compiler narrows the range of any matched name by that condition! An else -> arm at the bottom catches everything that earlier arms did not take.

Adder makes sure your match is watertight:

• Every possible value of the input must be handled by some arm; if any case or number is left out, the compiler lets you know with missingCoverage.
• If an earlier arm without a when guard already catches a value, a later arm for the same value could never be reached, so the compiler flags it with duplicateArm.
• Case patterns in a match arm are written cleanly without a leading dot (title ->, not .title ->); writing a dot triggers dottedArm.

enum Mode
  case title, playing, over
end
var mode: Mode = .title
var lives: Number<0...3> = 3
System.screen.border <- match mode
  title -> .blue
  playing -> .black
  over -> .red
end
System.screen.background <- match lives
  0 -> .red
  n when n < 3 -> Color(n + 7)
  else -> .black
end
when System.joystick[2].fire.pressed
  mode = mode.next()
  lives = lives -| 1
end

match Without a Value

You can also write match with nothing after the keyword to build a clean table of conditions—often much nicer to read than a long ladder of if ... else if ...! Each arm starts with when followed by a bool expression or an event. Adder checks the arms from top to bottom, picks the first one that holds, and skips working out the rest. A condition-table match must have at least one when arm and finish with an else -> fallback; leaving either out triggers conditionalMatch.

var lives: Number<0...3> = 3
System.screen.border <- match
  when lives == 0 -> Color.gray
  when System.joystick[2].fire -> Color.red
  else -> Color.black
end

Calls and Members

arguments ::= argument ( ',' argument )* ','?
argument  ::= ( name ':' )? expression | name '->' expression

Calls

To call a function or an op, write its name followed by its arguments in parentheses: apart(ball, bat). Adder always works out all of the arguments from left to right before running the function. You can pass arguments by position, or attach the parameter's name as a label—like apart(ball, b: bat)—and labeled arguments can appear in whatever order reads best. Each argument is checked against the parameter's declared type and range just as if you were storing it into a variable.

If a call does not line up with the declaration, the compiler tells you right away:

• badArgument when a label does not match any parameter name, when the same parameter is supplied twice, or when too many arguments are passed;
• missingArgument when a required parameter is left out;
• unknownFunction when the function has not been declared above the call.

fn apart(a: Number<0...296>, b: Number<0...296>): Number<0...296>
  if a > b then a - b else b - a end
end
var ball: Number<0...296> = 40
var bat: Number<0...296> = 100
gap <- apart(ball, b: bat)
System.screen.border <- if gap < 16 then .green else .black end

Declarations shows how to write your own functions and ops.

Members

A dot . after a value reaches for one of its members. Plain struct fields and properties need no parentheses (position.x, xs.first), while member functions that compute something take parentheses (score.digits(3)). When you declare a member function like fn Type.name(value: Type, ...), calling item.name(...) passes item (the value before the dot) into that first parameter automatically.

When the compiler already knows what type a place expects—for instance, assigning to System.screen.border or comparing against a Color—you can start with a bare dot like .red instead of spelling out Color.red. If you write .name in a spot where no specific type is expected yet, the compiler asks you to name the type with memberNeedsType. When a name before the dot begins with a capital letter, it refers to a type itself, giving you access to its cases (Color.red), its range bounds (Destination.first and Destination.last), and its type-level makers like Color.random() and Number.random(0...15).

struct Position(x: Number<u8>, y: Number<u8>)
fn Position.is_left(value: Position): bool
  value.x < 20
end
var position: Position = (x: 10, y: 12)
left <- position.is_left()
System.screen.border <- if left then .white else Color.black end

Asking a struct for a field it does not have raises unknownField, and asking a type or value for a member that does not exist raises noMember or unknownName.

Operations Over Lists

Lifted Operations

In Adder, you rarely need to write a loop just to do math on a list of numbers. Hand a list to an arithmetic or comparison operator and Adder automatically applies the operation to every element in turn, giving you back a fresh list of results! You can combine a list with a single value (which pairs with every element in the list) or combine two lists of the same length (which pair up slot by slot). Trying to combine two lists of different lengths raises arrayShapes.

Your own functions and ops get this superpower automatically too: if a function or op expects a single value for its parameter and you hand it a list instead, it runs across every element of the list—and for an op, each slot in the list even keeps its own independent memory from frame to frame! (If a parameter is explicitly declared to take a list, the function receives the whole list at once instead.)

const xs = [1, 2, 3]
const ys = [4, 5, 6]
fn half(x: Number<0...9>): Number<0...4>
  x / 2
end
sums <- xs + ys                         // [5, 7, 9]
scaled <- xs * 2                        // [2, 4, 6]
big <- ys > 4                           // [false, true, true]
halves <- half(ys)                      // [2, 2, 3]
System.screen.border <- Color(sums[0] + scaled[1] + halves[2])
System.screen.background <- if big[2] then .green else .black end

Reductions

When you want to boil an entire list down to a single summary value—like adding up column heights or checking whether any alien has reached the bottom row—use a reduction:

List reductions work purely on the current contents of the list—they keep no memory between frames—and their cycle cost scales with the number of elements in the list.

var drops: [6 of Number<0...999>] = [60, 200, 120, 300, 90, 250]
deep <- (drops > 160).count()
all_drops <- drops.sum()
first_deep <- (drops > 160).first_index()
when System.keyboard.space.pressed
  drops[0] = 400
end
System.screen.border <- if (drops > 350).any() then .red else Color(deep) end
System.screen.text[0][0..<4] <- all_drops.digits(4)
System.screen.text[1][0..<1] <- (first_deep ?? 0).digits(1)

map and filter

For custom element-by-element transformations, map and filter let you write a short arrow expression right inside the call:

• xs.map(n -> expression) works out expression for each element n of xs and gives back the list of results.
• xs.filter(n -> condition) tests each element n; where condition is true it keeps the element, and where condition is false it leaves nil in that slot, returning a list of optionals ([k of T?]).

Both keep the list's length intact and automatically skip over any slot that is already nil. Mapping over an optional list gives back an optional list, and if your map arrow itself produces an optional, Adder keeps it flat (T?) rather than wrapping an optional inside an optional. When you chain calls like xs.filter(...).map(...), each step finishes working out all of its elements in order before the next step in the chain begins.

const values: [3 of Number<u8>?] = [2, nil, 4]
kept <- values.filter(n -> n >= 3).map(n -> n - 1)  // [nil, nil, 3]
System.screen.border <- Color(kept[2] ?? 0)

A few guardrails keep arrows fast and predictable:

• The element name before -> is read-only and must be a fresh name not already in scope (reusing an outer name triggers shadowing).
• The expression after -> can read surrounding values, but it cannot hold frame-to-frame memory or side effects of its own—such as drawing a random number, testing an event, reading .previous(), or calling an op. The compiler flags any of those—or a filter arrow whose expression is not a bool—with collectionArrow. If you want to combine list elements with a random roll or an op value, bind that roll or op on its own line first and read its name inside the arrow.

map, filter, and sum(from:) also work on value-carrying events, as Events and Handlers describes.

Random Numbers

Games thrive on a little surprise! Number.random(range) draws a whole number from a range whose start and end are known at compile time (passed directly without an argument label), and Color.random() picks one of the sixteen colors.

roll <- Number.random(1...6)
const low = 2
sample <- Number.random(low..<(low + 8))
var shade: Color = .black
when System.keyboard.space.pressed
  shade = Color.random()
end
System.screen.background <- shade
System.screen.border <- Color(roll + sample)

Every random call site in your program has its own independent number generator under the hood, so adding a random starfield in one part of your code will never shift the dice rolls in another part. A call draws a fresh number only in the frames where its line actually runs—so a random call inside a when handler advances only when that handler fires. If you want one random roll to be shared by several places in the same frame, put the random call in a binding (roll <- Number.random(1...6)) and read roll wherever you need it. Restarting the program replays the exact same sequences from the beginning, making tricky bugs easy to reproduce.

Even better, Adder draws from ranges of any size—not just powers of two—without ever needing a slow division instruction! Because the generator is tailored to the range at compile time, a range with changing endpoints is flagged with rangeEndNotFixed, and passing anything other than a range to Number.random triggers randomNeedsRange. Finally, because a plain fn promises to return the exact same answer every time you give it the same arguments, calling random inside a fn is caught with randomImpure.

Declarations

Every game or demo you build is made of things you name: a ship's horizontal position, the number of lives left, a melody table, a helper formula for checking collisions, or the live rule that paints the screen border. In Adder, a declaration introduces a name and makes a clear promise about when—and how—its value can change:

• A constant declaration, written as const name = expression, fixes a value at compile time. Inside a handler or its loops, = instead assigns to existing var state; it does not introduce a constant.
• A variable, written with var, holds state from frame to frame and changes only when an event handler assigns it a new value.
• A binding, written with <-, is a live wire: it always equals its expression, updating automatically as the values it reads change.
• Functions (fn), ops (op), and work (work) give names to calculations, while types (type, enum, struct) give names to kinds of values.
• at places a value at a specific spot in memory, and include brings another source file into your project.

declaration ::= constant | variable | binding | placed-value | output-declaration
              | function | op-declaration | work-declaration
              | type-alias | enum-declaration | struct-declaration | include | declaration-match | declaration-if

Declarations stand at the top level of your program, one per line, or inside a case as Events and Handlers explains. You can arrange your declarations and handlers in whatever order tells the story of your program best, with one simple rule: declare a name above the first line that reads it.

Names and Scope

Every declared name follows the spelling rules in Names. Type names always start with a capital letter (Ship, Score), while constants, variables, bindings, functions, and ops always start with a small letter or an underscore (lives, ship_x). Starting a non-type declaration with a capital letter triggers capitalizedDeclaration.

Once you declare a name, it is in scope from that line all the way to the bottom of the program. Any line that reads a name or calls a function must appear after its declaration; reading a name too early raises unknownName (or unknownFunction for a call). There is just one special exception: a binding can look back at the previous frame's value of a binding written further down the page, as A Binding That Reads Itself shows.

Each name in your program—across all included files—is declared only once. Declaring the same top-level name a second time raises duplicateDeclaration, and reusing a top-level name for a parameter or local variable inside a block raises shadowing so you never lose track of which value you are looking at.

Built-in type names, System, and scratch are reserved for the machine and cannot be redeclared (builtinName). Built-in member names like digits and sum, however, are completely free for you to use as variable or function names of your own.

The compiler checks every single declaration in your file, even if nothing calls or reads it yet. An unused function or struct member is checked for undeclared names, missing types, or misplaced statements (like a wait outside a handler) just as thoroughly as one you call every frame. Generic functions with type parameters are checked up front for their names, types, and statement placement, and then checked for exact number ranges at each call site. And when it is time to emit your program, any declaration that nothing uses is stripped away—it costs zero bytes in your final binary!

Constants

Write const name = expression to declare a constant whose value is locked in when the program compiles. For number constants, the compiler bakes the number straight into the machine instructions that use it, so the constant does not even take up a byte of storage in memory.

constant ::= 'const' name ( ':' type )? '=' expression

A constant's expression can combine literals, earlier constants, pure functions, and type makers like Color.red, ScreenCode("ADDER"), or Shape([...]). You can also put a constant list, struct, or picture in a constant, or give a short nickname to a branch of the hardware tree—like screen = System.screen—and use screen as a stand-in for that path.

const columns = 40
const half = columns / 2
const table = [3, 1, 4]
const screen = System.screen
var lane: Number<0...39> = half
screen.border <- Color(table[1] + lane % 8)

When you leave off the : type annotation, the constant takes the exact value and tightest range of its expression. When you write a : type annotation, the compiler verifies at compile time that the constant fits inside that type, flagging literalDoesNotFit if it steps outside.

Because a constant is worked out before the program ever starts, it cannot read anything that changes while the program runs—no variables, bindings, live device inputs, or ops (constantChanges). And once declared, a constant stays constant forever: trying to assign a new value to one in a handler raises notAssignable. Constants cannot hold events either, as Events explains.

Variables

Write var name = expression to declare a variable—a slot in memory that remembers its value from one frame to the next, like the player's score, remaining lives, or current game mode. The expression after = sets the variable's starting value when the program boots up, and from then on only an event handler can change it (either directly with = or by calling a mut fn on a struct stored in the variable).

variable ::= 'var' name ( ':' type )? '=' expression

Every var declaration must include a starting value (= expression). Because the program works out that starting value as it starts up, the starting expression can read constants, earlier variables, bindings, functions, and even live hardware inputs like the joystick!

enum Mode
  case title, playing
end
var lives: Number<0...3> = 3
var mode = Mode.title
var start_x: Number<-1...1> = System.joystick[2].dx
when System.joystick[2].fire.pressed
  lives = lives -| 1
end
System.screen.border <- Color(lives + start_x + 1)

If you omit the : type annotation on a var, it takes the type of its starting expression—and for a number, it widens to The Default Number (-32,768...32,767) unless you give it a range like Number<0...3>. If the starting value is a bare dot-name like .red, add a type annotation (var shade: Color = .red) or write Color.red so the compiler knows which set the case belongs to (memberNeedsType).

Each top-level variable occupies just the bytes needed by its type. Handlers and functions can also declare temporary local var values that live only while that block runs, as Statements describes.

Bindings

Write name <- expression to declare a binding. Think of <- as a live connection: instead of holding an old value until something overwrites it, a binding always equals its expression. Whenever any variable or input that the binding reads changes, the binding reflects the new answer automatically. Because a binding is defined entirely by its formula, a handler can never assign to it (notAssignable).

binding ::= ( 'fast' | 'small' )? name ( ':' type )? '<-' expression
          | ( 'fast' | 'small' )? place '<-' expression

var lives: Number<0...3> = 3
warning <- lives == 1
spare: Number<0...2> <- lives -| 1
System.screen.border <- if warning then .red else .black end
System.screen.text[0][0..<1] <- spare.digits(1)
when System.keyboard.space.pressed
  lives = lives -| 1
end

Without a : type annotation, a binding takes the exact type and range that the compiler proves for its expression. With a : type annotation, the binding takes that declared type (and checks the value at runtime if the compiler cannot prove the expression already fits). A binding can also give a name to an event—for instance, jump <- System.joystick[2].fire.pressed—so that when jump handlers can listen to it; see Events.

Putting the keyword fast in front of a binding asks the compiler to spend extra bytes of memory or lookup tables to save CPU cycles on that line, as Costs and the Frame explains.

Outputs

When the left side of <- is a hardware or memory place rather than a fresh variable name, the binding is an output: System.screen.border <- expression keeps the screen's border color wired to that expression every frame. An output target can be any writable spot in the hardware tree—the border, the background, a row or cell of screen text, a sprite, a voice—or a memory location declared with at. The System Device Tree tours all the built-in output places and the types they accept.

To keep your hardware state crystal clear, each output place is driven by a single binding in your program (or within a case). Wiring two bindings to the same output place triggers overlap.

Handlers never write directly to outputs (notAssignable). Whenever you want handlers to control what appears on an output, have the handlers update a var and wire the output to that var with <-.

A Binding That Reads Itself

Within a single frame, a binding has no value until its expression finishes running—so a binding cannot read its own current-frame value, nor can two bindings read each other in a circle (bindingLoop).

What a binding can do is read what its value was in the previous frame using .previous(from: initial). The from: argument supplies the starting value for the very first frame before there is a previous frame to look back at:

tick: Number<0...99> <- tick.previous(from: 0) +% 1
System.screen.border <- Color(tick % 16)

.previous(from: ...) can even read a binding that is declared further down the page, letting two bindings feed into each other across frames! When a binding reads a later binding through previous, that later binding must write out its : type annotation so the compiler knows its size up front (forwardNeedsType).

Order in a Frame

Every television frame follows a clean, predictable rhythm:

1. First, the program samples the hardware inputs (keyboard, joysticks, paddles) and works out which events fired this frame.
2. Next, the when handlers whose events fired run from top to bottom in the order they are written.
3. Finally, once all handlers have finished, every output binding updates the screen and sound hardware with the final value of its expression.

Inside a handler, any assignment to a var takes effect right away on the very next line—and if a handler reads a binding, that binding gives the up-to-the-instant value based on the current variables!

var n: Number<0...4> = 1
doubled <- n * 2
var seen: Number<0...8> = 0
when System.screen.frame
  n = 3
  seen = doubled
end
System.screen.border <- Color(seen)

In this example, seen becomes 6 on the very first frame: the handler sets n to 3, and reading doubled on the next line uses that new 3 right away.

What about a binding that remembers history across frames—one that uses .previous(), an op, or a stateful member like .sum() or .count()? Those history-keeping bindings advance once per frame, so reading the same stateful binding in several places during a single frame always gives you the exact same snapshot. Events and Handlers walks through the frame cycle in complete detail.

Output Declarations

If you find yourself wiring the same group of hardware outputs together—say, setting both the border and background colors from one mood color, or configuring a sprite pair—you can bundle them into a reusable output declaration:

output-declaration ::= 'output' name '(' name ':' type ')' newline output-line* 'end'

output frame_color(c: Color)
  System.screen.border <- c
  System.screen.background <- c
end
var hue: Number<0...15> = 0
frame_color <- Color(hue)
when System.keyboard.space.pressed
  hue = hue +% 1
end

When you wire frame_color <- Color(hue), the parameter c receives Color(hue) and drives every output binding inside the block. An output block may contain output bindings (including bindings to other declared outputs) and asm blocks; putting any other kind of line inside triggers outputBody, and using <- on a name that is not an output triggers outputTarget. Just like a built-in hardware output, your custom output takes a single <- binding and cannot be assigned with = inside a handler.

Functions

A function (fn) is a named, self-contained calculation. Give it the same argument values and it will give you back the exact same answer every time, with no hidden state or surprises.

function       ::= ( 'fast' | 'small' )? 'fn' function-name '(' parameters? ')' ( ':' type )? newline
                   statement* expression newline 'end'
function-name  ::= name | owner '.' name
owner          ::= name | 'Number'
parameters     ::= parameter ( ',' parameter )*
parameter      ::= name ( ':' type )?

fn apart(a: Number<0...296>, b: Number<0...296>): Number<u16>
  if a > b then a - b else b - a end
end
bat: Number<0...296> <- (System.joystick[2].dx * 4).sum(from: 136)
ball: Number<0...296> <- System.screen.frame.cycle()
close <- apart(ball, b: bat) < 16
System.screen.border <- if close then .green else .black end

Parameters and Results

The head of a fn (or an op) declares its parameters inside the parentheses, and each call to it supplies the argument values for that run. Ordinary parameters are read-only input names written without var: each call hands them their value, they are visible only inside the body, and they never hold writable storage of their own.

In a fn or op head, each parameter can declare an explicit : type to check arguments against, or omit : type and infer its type and numeric range from the argument passed at each call site. Likewise, a fn head can declare : type after the closing ) to check the returned value against, or omit : type to infer the result type from the body's final expression (while mut fn methods, which perform actions without returning a value, still omit : type and work declarations still require : type on every parameter and result with parameterNeedsType / resultTypeNeeded). Each parameter in a signature needs a distinct name (duplicateParameter).

Inside the body, the last line is the expression that produces the function's return value. Before that final line, you can write statements to help work out the answer: local constants with const, local variables with var, if and match statements that update those local variables, and bounded for loops, as Statements describes. Because parameters and local const values are read-only inputs for the duration of the call, trying to assign a new value to either one triggers localImmutable—if you want a working value you can step or update inside the function, copy it into a local var first.

fn middle(low: Number<u8>, high: Number<u8>): Number<u8>
  const sum_of = low + high
  sum_of / 2
end
fn add_up(values: [4 of Number<u8>]): Number<u16>
  var t: Number<u16> = 0
  for v in values
    t = t + v
  end
  t
end
mid <- middle(3, 9)
all_of <- add_up([1, 2, 3, 4])
System.screen.border <- Color(mid % 16)
System.screen.background <- Color(all_of % 16)

Keep the shape of a function body in mind:

• Every line before the last line must be a statement that does work (like declaring or updating a local variable). Leaving a bare expression on an earlier line where its result is thrown away triggers resultUnused.
• The last line must be an expression that produces the return value; ending a function with a statement triggers valueBlockEmpty.
• When the last line of the body is an if or a match, each branch or arm follows the same pattern: any lines before the branch's final line run as statements first, and the final line of each branch supplies the return value!

enum Size
  case little, medium, large
end
fn bonus_for(size: Size): Number<u8>
  var points: Number<u8> = 0
  match size
    little -> points = 1
    medium -> points = 3
    large -> points = 6
  end
  if size == .large then points = points + 2 end
  match size
    little -> points
    medium ->
      points = points + 1
      points
    large -> points
  end
end
var size: Size = .large
System.screen.border <- Color(bonus_for(size))

At the call site, you can pass arguments in parameter order (apart(ball, bat)) or attach a parameter's name as an optional label (apart(ball, b: bat)). Supplying an unknown label, repeating a parameter, or passing too many arguments raises badArgument, and leaving out a required parameter raises missingArgument. An argument whose constant value or range cannot fit the parameter's declared type is caught at compile time with literalDoesNotFit; otherwise, Adder checks changing arguments (and the function's return value) at runtime whenever the compiler cannot prove they already fit.

What a Function May Read

To guarantee that a function always returns the same output for the same inputs, a fn can only read:

• its own parameters and local names,
• top-level constants,
• other functions, and
• (when written inside a struct block) the fields of its own struct.

This rule applies across all functions: free fn declarations as well as a struct's fn, mut fn, and maker functions. A function cannot reach out to read a top-level var, a binding, or a hardware device directly; trying to do so triggers operationScope.

Whenever a function needs a changing value from the outside—like a sprite's coordinate or a joystick direction—simply add a parameter for it and pass the value in at the call site! That small habit makes your functions much more flexible too. Consider a Ship struct with a mut fn steer:

struct Ship(x: Number<0...39>)
  mut fn steer(dx: Number<-1...1>)
    x = x +| dx
  end
end
var ship = Ship(20)
when System.screen.frame
  ship.steer(System.joystick[2].dx)
end

If steer were wired directly to System.joystick[2].dx inside the struct, every Ship in your game would be stuck on port 2. By taking dx as a parameter, player one's ship can steer with port 2 while player two's ship steers with port 1—or even with an AI routine!

Along the same lines, a function cannot modify a top-level variable (functionSets), roll a random number (randomImpure), use .previous() or any other frame-memory operation (memoryOutsideBinding), pause with wait (waitOutsideHandler), or call itself (recursion).

You can call a function from any binding, handler, op, or later function declared below it.

Member Functions

When you write a function's name as Type.name, it becomes a member function of Type. Its first parameter receives the value written before the dot when you call value.name(...):

struct Position(x: Number<u8>, y: Number<u8>)
fn Position.is_left(value: Position): bool
  value.x < 20
end
var position: Position = (x: 10, y: 12)
left <- position.is_left()
System.screen.border <- if left then .white else .black end

You can attach member functions to any type you declare (struct, enum, or type alias), as well as to Number, bool, Event, or even a generic type parameter like T. The first parameter's type must match the type before the dot in the function's name (wrongType), and every field, function, and op on a given type must have a distinct name (memberOverlap).

For structs, you can also write member functions directly inside the struct ... end block, as Struct Blocks shows.

Type Parameters

Want to write a helper function that works on a list of any element type or any length? Use a type parameter or a length parameter right in the function's signature:

• A single capital letter, like T, stands for any type supplied by the call.
• A single small letter inside a list type's length slot, like n in [n of T], stands for the length of the list passed at the call site—and inside the function body, you can read n as a number!

If the same letter appears more than once in one signature (like fn keep(values: [n of T]): [n of T]), every occurrence stands for the exact same type or length.

fn keep(values: [n of T]): [n of T]
  values
end
fn length_of(values: [n of T]): Number<u16>
  n
end
const numbers = keep([1, 2, 3])
const flags = keep([true, false])
size <- length_of(numbers)
System.screen.border <- Color(size)

If a call passes two arguments that disagree on what T or n should be, the compiler catches the mismatch with parameterAgreement.

You can also combine type parameters with optionals and events: T? matches an optional of any type, and Event of T matches a value-carrying event of any payload type. Because single capital letters are reserved for type parameters, any type you declare yourself (type, enum, or struct) must have a name at least two letters long (parameterTypeName).

Ops

While a fn is a pure calculation with no memory of the past, an operation (op) is a reusable calculation that remembers earlier frames—perfect for velocities, smooth filters, edge detectors, timers, and bouncing movement! An op looks a lot like a function and ends with its result expression, but its body is made of <- bindings that can look back at previous frames.

op-declaration ::= ( 'fast' | 'small' )? 'op' function-name '(' ( op-parameter ( ',' op-parameter )* )? ')'
                   ( ':' type )? newline op-line* expression newline 'end'
op-parameter   ::= name ( ':' type )?
op-line        ::= name ( ':' type )? '<-' expression newline

op speed(x)
  x - x.previous()
end
bat: Number<0...296> <- (System.joystick[2].dx * 4).sum(from: 136)
moving <- speed(bat) != 0
System.screen.border <- if moving then .yellow else .black end
System.screen.sprite[0] <- (x: bat, y: 170)

Just like a function head, an op head declares its parameters inside parentheses and each call supplies the argument values (optionally labeled with the parameter's name). Those parameters are read-only input names written without var, visible only inside the op body and given their fresh value by each call. Unlike a fn parameter, an op parameter can leave out its : type annotation and automatically adopt the exact type and range of the argument passed at each call! When an op parameter does include a : type, it checks the argument against that type just like a function parameter. The : type after the closing ) is optional too; when written, it sets the result type of the op.

Notice what happens in op speed(x) above: x is a read-only input parameter, not a variable you assign to, yet x.previous() remembers what x was on the previous frame! Remembering prior samples of an input parameter is part of the op call's own frame-to-frame history—it never turns the parameter into writable storage.

Inside an op, you can read its parameters, top-level constants, functions, and other ops (trying to read a top-level var or binding directly raises operationScope). Every line before the final result expression in an op body must be a <- binding (opHolds).

Because an op carries frame-to-frame memory, you call it inside a binding (<-), never inside a when handler, a plain fn, or the starting value of a var (memoryOutsideBinding). And each written op call site in your program gets its own separate memory across frames: if two bindings both call speed(...), each call tracks its own history independently. Even better, if you pass a list to an op parameter that expects a single item, each slot of the list gets its own separate history too!

Remembering With previous

Inside a binding or an op, x.previous() gives the value x had on the previous frame. On the very first frame—before there is a previous frame—x.previous() simply equals the current value of x. If you want a specific starting value on the first frame instead, write x.previous(from: value).

When a binding inside an op (or at the top level) reads its own previous value—or reads the previous value of a binding written further down in the block—you must include from: so the first frame has a known starting point; leaving from: off raises recurrenceNeedsFrom or forwardNeedsFrom.

All of Adder's other history-keeping helpers—such as .sum(), .count(), .cycle(), and .sampled()—are built on this same foundation, and Events and Handlers introduces each of them.

Destination and start

Sometimes an op wants to adapt to the range of whatever binding is receiving its output—for example, a bounce operation that bounces between 0 and 159 for one sprite and between 24 and 255 for another! Inside an op body, the special type name Destination stands for the declared type of the binding receiving the call's result, and Destination.first and Destination.last give the lower and upper ends of that range. Because Destination comes from the receiving binding's annotation, calling such an op in a binding without a : type annotation triggers operationNeedsRange.

Inside an op, the keyword start is a bool that is true while the op works out its very first value (or when it is reset) and false on subsequent frames.

op bounce(begin, speed: Number<-15...15>)
  moved <- pos.previous(from: begin) + dir.previous(from: speed)
  dir: Number<-15...15> <- if moved < Destination.first or moved > Destination.last then
    -dir.previous(from: speed)
  else
    dir.previous(from: speed)
  end
  pos: Destination <- if moved < Destination.first then
    Destination.first + (Destination.first - moved)
  else
    if moved > Destination.last then
      Destination.last - (moved - Destination.last)
    else
      moved
    end
  end
  pos
end
x: Number<0...159> <- bounce(150, 4)
System.screen.sprite[0] <- (x: x, y: 50)

on: and reset:

Every op—whether you wrote it yourself or it is built into Adder—automatically accepts two optional event arguments at any call site: on: and reset:.

• on: sets the pace at which the op steps forward. The op works out its initial value on the first frame, and after that it updates only in frames where the on: event fires. On frames where the on: event does not fire, the op freezes its result, its internal bindings, and its previous history in place—costing only the quick check of the event!
• reset: restarts the op fresh in any frame where the reset: event fires, even if on: would otherwise pause it that frame. The op (along with any nested ops or history-keeping members inside it) recomputes its first-frame value from its current arguments, and start becomes true again for that frame. If both reset: and on: fire in the same frame, reset: wins.

op travel(initial)
  position: Destination <- if start then initial else position.previous(from: initial) +% 1 end
  position
end
moving <- System.screen.frame when System.joystick[2].fire
x: Number<0...159> <- travel(20, on: moving, reset: System.keyboard.space.pressed)
System.screen.sprite[0] <- (x: x, y: 50)

Both on: and reset: require an event (onNeedsEvent). Plain fn functions do not keep history across frames, so passing on: or reset: to a fn call is flagged with badArgument.

Work

What if you have a big calculation—like generating a dungeon map, tallying a large table, or scoring a board—that takes too many CPU cycles to finish inside a single television frame without delaying the screen update? Declare it with work Type.name(...)! Calling a work declaration starts a background job that captures its arguments and chips away at the calculation across frames, using the cycles left over in each frame after your regular handlers and outputs finish.

work-declaration ::= 'work' name '.' name '(' parameters? ')' ':' type newline
                     statement* expression newline 'end'

A work declaration is always written as a member of a type declared by your program (often a type alias for a list or a struct), and its body follows the same rules as a fn body. You do not need to sprinkle manual pause points through your loops: the compiler automatically splits the body across loop iterations! A short loop that fits comfortably inside one frame runs in a single part; a longer loop runs a few iterations per frame across several parts; and a loop-free body runs as one part. If a single turn of a loop has an unbounded cost or is too heavy to fit inside a frame at all, the compiler tells you right away and names the loop.

type Samples = [4 of Number<u8>]
work Samples.tally(input: Samples): Number<u16>
  var amount: Number<u16> = 0
  for sample in input
    amount = amount + sample
  end
  amount
end
const samples: Samples = [1, 2, 3, 4]
answer: Number<u16>? <- samples.tally()
System.screen.text[0][0..<5] <- if amount = answer then amount.digits(5) else "wait " end

Because a job may take several frames to finish, binding its result with <- produces an optional type T?: the binding holds nil while the job is still working, and switches to the finished value T as soon as the job completes. (Giving the binding a non-optional type T raises wrongType.) If any argument to the work call changes while a job is in flight, Adder automatically starts a fresh job with the new arguments to replace the unfinished one.

Want a compile-time guarantee that your background job always finishes within a set number of frames? Tack .within(frames: n) onto the call in a binding! The compiler proves from the frame cycle budget that the job finishes in n frames or fewer—flagging jobDeadline if it cannot prove the deadline—and the check adds zero runtime cost to your program.

You can also step a job manually inside a var: write var job: Job of T = value.name(...), and in a handler call job.step() to run one part and get back T?, or call job.run() to finish the remaining work immediately in that handler turn and get back T. You can even line up multiple jobs in a queue to run one after another, as Events and Handlers explains.

Type Declarations

Adder gives you three ways to introduce your own types: type aliases, enum declarations, and struct declarations. Just like other declarations, a type must be declared above any line that names it (unknownType). Every type name starts with a capital letter and is at least two letters long; starting a type name with a small letter triggers aliasName, enumName, or structName.

type-alias ::= 'type' name '=' type

Type Aliases, Enums, and Structs describe the values these types create. While an enum block contains only case lines, a struct can open a block to hold both its fields and its member functions!

Struct Blocks

A struct block lists its fields and functions one per line between struct Name and end. You can either list all the fields on lines inside the block, or put the plain fields in parentheses on the struct Name(...) header line and use the block body for var fields and member functions.

struct-member ::= name ':' type newline
                | 'var' name ( ':' type )? '=' expression newline
                | ( 'fast' | 'small' )? 'mut'? 'fn' function-name '(' parameters? ')' ( ':' type )? newline
                  statement* expression? newline 'end'

There are two kinds of fields in a struct block:

• Plain fields (step: Number<u8>) are supplied when you construct the struct, such as Score(step: 10).
• Variable fields (var points: Number<0...999> = 0) start at the initial value written in the declaration. Because they already have their starting value, the struct's maker does not take an argument for them (passing one raises badArgument).

Putting any line other than a field or a fn inside a struct block raises structBody.

struct Score
  step: Number<u8>
  var points: Number<0...999> = 0
  mut fn award()
    points = points +| step
  end
  fn text(): [3 of Char]
    points.digits(3)
  end
  fn Score.started(step_size: Number<u8>): Score
    Score(step: step_size)
  end
end
var score = Score.started(10)
when System.keyboard.space.pressed
  score.award()
end
System.screen.text[0][0..<3] <- score.text()

Functions inside a struct block come in three flavors:

1. Read-only member functions (fn name(...)): Written without a type prefix before the name. You do not write a parameter for the struct itself—all of the struct's fields and other member functions are automatically in scope by name! A plain fn promises not to change any of the struct's fields (even indirectly through another call); trying to modify a field inside a plain fn raises structMutationUndeclared.
2. Mutating member functions (mut fn name(...)): Marked with mut so they can update the struct's fields. A mut fn does not have to return a value (so its : type is optional), and handlers can call it on a var struct, a field of a var, or an element of a var list. Because it modifies the struct in place, calling a mut fn inside a binding or on a constant struct is caught with structChangingPlace. (mut fn is only for struct blocks; writing mut fn at the top level triggers structMutationMethodOnly.)
3. Maker functions (fn StructName.name(...)): Written with the struct's own type name before the dot, like fn Score.started(...). A maker belongs to the type as a whole rather than to an existing instance, so the struct's fields are not in scope inside it, and you call it on the type name (Score.started(10)). Prefixing a function inside a struct block with some other type's name triggers structMakerOwner.

Placing a Value in Memory

Sometimes you want a variable, a table, or an output to live at an exact address in the machine's memory—for instance, to share a buffer with an asm block, place a custom screen matrix on a hardware boundary, or peek and poke a cartridge register. Write name: T at address to pin a value to a fixed memory address:

placed-value ::= name ':' type 'at' whole-literal ( '<-' expression )?

seen: Number<u8> at 0xC000
shade: Number<u8> at 0xC001 <- seen +% 1
System.screen.border <- Color(seen % 16)

Every time your program reads seen, it reads straight from that address in memory, so it immediately sees any byte written there by hardware or assembly code. The address after at must be a whole-number literal (addressNeeded) where the type actually fits within the machine's memory (hardwareInvalid). Unlike a var, a placed value takes no starting = expression. When you attach <- expression, the placed value becomes an output that Adder updates at that address every frame; without <-, a single placed value is read-only from Adder handlers (registerAssigned).

You can also place an entire list at a fixed address, and handlers can freely read and write its elements in place:

tiles: [16 of Number<u8>] at 0xC000
when System.screen.frame
  tiles[0] = tiles[1] +% 1
end
System.screen.border <- Color(tiles[0] % 16)

If you bind a placed list as the whole text screen, it must start on a 1,024-byte boundary where the video chip can reach it (listOffBoundary).

To keep your program from stepping on its own toes, the compiler checks every at address against your memory layout:

• Placing a list over addresses 0 and 1 (the processor's built-in I/O port) is caught with placedOnPort.
• Two placed values that overlap each other's bytes are caught with placedOverList.
• Any placed value that collides with your compiled code, variables, or runtime routines is caught with placedOverProgram.
• Placed lists get three extra safety checks so a table write never clobbers the machine: they cannot overlap the zero page handed out by the compiler, the processor stack, or the runtime's interrupt vectors (placedOverRuntime); they cannot overlap the active text screen unless the list is that screen (placedOverScreen); and in a bitmap program, they cannot overlap the picture's memory (placedOverPicture).
• A single placed number only checks against your compiled program and other placed values, leaving you free to point it at special addresses as long as you keep it clear of the rest.

Assembly maps out how a compiled Adder program arranges memory.

Include and Project Files

As your game grows, you can split your types, art tables, sound helpers, and cases across multiple files and bring them together with include "path":

include ::= 'include' string-literal

include "lib/world"
var lane: Number<0...39> = 0
when System.screen.frame
  lane = wrap(lane)
end

Any folder containing main.adder acts as a project, with main.adder as the starting file; a standalone .adder file treats its own folder as its project root. Every include path is resolved from that project root folder—even when written inside a file in a subfolder—and you can leave off the .adder extension, so "lib/world" and "lib/world.adder" refer to the exact same file.

If several files include the same helper file (or even include each other in a circle), Adder includes each file just once, at the spot where it is first mentioned. All files in a project share one flat namespace and follow the same top-to-bottom rule as a single file: a declaration from an included file is ready to use on any line after the include statement. The compiler typechecks every declaration in every included file, and then strips away any unused declarations so your final binary only pays for what your program actually uses.

Include paths use forward slashes / between folder and file names made of ASCII letters, digits, -, _, and ., with no name starting with a dot. Absolute paths, backslashes, empty path parts, and . or .. names are not allowed, and referencing a file that does not exist in the project raises includeMissing.

Write your include lines at the top level of a file, never tucked inside a handler or block.

Declarations in a Match

What a case declares exists only while the case matches. Among declarations, a match or an if holds declarations: bindings, variables, naming lines and handlers. Only the chosen case runs; the other cases cost the frame nothing.

declaration-match ::= 'match' expression? newline declaration-case+ 'end'
declaration-case  ::= ( 'fast' | 'small' )? ( pattern ( 'when' expression )? | 'when' expression | 'else' ) '->' declaration-body
declaration-body  ::= declaration-line | newline declaration-line*
declaration-if    ::= ( 'fast' | 'small' )? 'if' condition 'then' declaration-body
                    ( 'else' 'if' condition 'then' declaration-body )*
                    ( 'else' declaration-body )? 'end'
declaration-line  ::= declaration | handler | declaration-match | declaration-if

enum Scene
  case title, game
end
var scene: Scene = .title
var rounds: Number<0...99> = 0
match scene
  title ->
    System.screen.border <- .blue
    System.screen.text[11][15..<25] <- "PRESS FIRE"
    when System.joystick[2].fire.pressed
      scene = .game
    end
  game ->
    var time_left: Number<0...9> = 9
    System.screen.border <- .green
    System.screen.text[0][0..<1] <- time_left.digits(1)
    when System.screen.frame.every(50)
      time_left = time_left -| 1
    end
    when start
      wait(seconds: 10)
      rounds = rounds +| 1
      scene = .title
    end
end

The value after match may be any value a statement match takes: a number, a named set such as Color, an enum, a bool, an optional, a list or a struct. Every possible value needs a case, or an else -> for the rest. Each case's lines begin on the line below its ->.

A number may have whole-number cases such as 0 ->; a named set uses its bare names, such as red ->. An optional needs nil -> for an absent value. A name pattern such as n -> holds the whole value, or an optional's present value, read-only throughout the case. That case starts again when its named value changes; an else -> case keeps its variables while the value still selects it.

var level: Number<0...9> = 1
match level
  0 ->
    System.screen.text[0][0..<1] <- "-"
  n ->
    System.screen.text[0][0..<1] <- n.digits(1)
end
when System.keyboard.space.pressed
  level = level +% 1
end

A pattern for an enum case that carries fields names them, as a statement match does: over(score) -> or over(score: final) ->. The names hold the case's values, have the fields' types, and can be read anywhere in the case: its bindings, handlers, constants and nested match. A pattern written without fields binds none. The compiler refuses a field the case does not have with unknownField, and an assignment to a field's name with notAssignable.

enum Flow
  case title
  case over(score: Number<0...99>)
end
var flow: Flow = .title
var points: Number<0...99> = 0
match flow
  title ->
    System.screen.border <- .blue
    when System.joystick[2].fire.pressed
      points = points +| 7
      flow = .over(score: points)
    end
  over(score) ->
    System.screen.border <- .red
    System.screen.text[0][0..<2] <- score.digits(2)
    when System.joystick[2].fire.pressed
      flow = .title
    end
end

Conditions on Cases

A case may add when condition after its pattern. The first pattern and condition that fit choose the case, just as in a statement match. Conditions are read with the value after match each frame; a condition changing can end one case and start another while the value after match stays equal.

enum Mode
  case game
end
var mode: Mode = .game
var lives: Number<0...3> = 3
match mode
  game when lives == 0 ->
    System.screen.border <- .red
  game ->
    System.screen.border <- .green
end
when System.keyboard.space.pressed when lives > 0
  lives = lives - 1
end

Without a value after match, write ordered when condition -> cases and a final else ->. A when line without the case arrow is a handler inside the case. Either case head may begin with fast or small.

held <- System.joystick[2].fire
match
  when held ->
    System.screen.border <- .green
  else ->
    System.screen.border <- .blue
end

Declarations in an If

A declaration if follows the same lifetime rule. A boolean head chooses its true or false case; else if checks heads in order, stopping at the first one that succeeds. An absent else declares nothing while the condition is false.

var paused = false
System.screen.text[10][17..<23] <- "GAME  "
if paused then
  System.screen.text[10][17..<23] <- "PAUSED"
end
when System.keyboard.space.pressed
  paused = not paused
end

An optional head such as if held = item and held > 0 then captures the present value once. Its name is read-only throughout the selected case, and changing that named value starts the case again. Later else if heads are not read after an earlier one succeeds. fast or small before if applies to all its cases; an inner mark decides its own code.

A case may put exactly one declaration after -> on the same line. A handler there can hold its own multi-line body, ending at its own end; another declaration below the completed inline case is statementAfterArm. A one-line if keeps its branches and closing end on that line.

When a Case Starts and Stops

When a handler changes the value after match, the new case begins in the next frame. The case that ends stops its handlers, including the ones that are waiting. The case that begins gives its variables their first values, shows what it binds, and starts its handlers from the top; its start happens in its first frame. A case starts again when the value after match moves to another case, or when a field the case names changes. Setting flow = .over(score: 12) while over(score: 5) runs ends the case and starts it again in the next frame, because over(score) names score. A case that names no fields, such as level -> or else ->, keeps running when only the fields change. A case that names some of its case's fields starts again for those and ignores the others. Each case decides from its own line, so a sibling written with fields does not change it. Setting a value equal to the one it has changes nothing. A variable declared above the match keeps its value as cases change, and a handler outside every case keeps running and waiting.

A case may bind a part of the screen, the border or a sprite that the lines outside the match also bind. While the case shows, its line decides that part; when it ends, the outer line decides it again. Two lines at one level cannot both bind the same part, and the compiler refuses the second with overlap.

What a Case Holds

A case holds bindings, var lines, constants, handlers, and nested match or if blocks that hold declarations. Types, functions, ops, placed values and queues belong to the whole program, so the compiler refuses them in a case with caseDeclaration, or with caseNotBuilt for what it cannot yet build in a case.

A case that has too much to show in one frame begins over several frames. A canvas's new picture is drawn with the screen blank until it is ready. Costs and the Frame describes the limits.

Events and Handlers

Bindings keep your screen and sound wired up from frame to frame, but a game also needs moments when things happen: a player taps the space bar, a fresh frame begins, a score ticks up, or a timer rings. An event happens in some frames and not in others. A when handler listens for an event and runs its statements in each frame where that event fires. Only a handler can change a variable, act on a device, pause with wait, or loop forever.

var hue: Number<0...15> = 0
when System.keyboard.space.pressed
  hue = hue +% 1
end
System.screen.border <- Color(hue)

Handlers

A handler starts with when and an event, lists the statements to run, and closes with end. It stands at the top of a program or inside a case, never tucked inside another handler or a function. Putting fast before when spends extra bytes of code to save cycles in that handler alone, as Costs and the Frame describes.

handler ::= ( 'fast' | 'small' )? 'when' ( name '=' )? expression newline statement* 'end'

The expression after when must be an event—a moment in time, not an ongoing state. A plain yes-or-no value can stay true across many frames, so if you write one after when, the compiler catches it with onNeedsEvent and suggests the event you probably meant. Write when System.joystick[2].fire, for instance, and the message points you to System.joystick[2].fire.pressed for the single frame the button goes down. When you really do want something to run in every frame while the button is held, filter the frame beat with System.screen.frame when System.joystick[2].fire, as Filters describes.

Inside a handler you write statements: assignments, local var lines, if, match, for, and device actions (see Statements), along with guard, wait, and forever from this chapter. Bindings (<-) live outside handlers, where they stay wired up continuously; if you slip a <- inside a handler, the compiler flags it with actionNeeded and reminds you to assign a variable with = instead.

Inside a handler, if chooses statements to run. Among declarations, if chooses declarations that exist only while their case matches; see Declarations in an If.

Handlers in a Frame

Every television frame follows the same tidy three-step rhythm:

1. The machine reads its inputs and decides which events happen in this frame.
2. The handlers whose events happened run one after another, from top to bottom in the order you wrote them.
3. The outputs—such as the screen, the border, and the sprites—show the fresh values that the handlers left behind.

Because handlers run in written order, each handler sees every change that an earlier handler made in the same frame. Suppose a key-press handler sets age = 0 and a frame handler below it adds one: age ends that frame at 1. Put them in the opposite order and age ends the frame at 0. Whenever two cases belong to the same decision, folding them into a single handler makes your intent crystal clear:

var age: Number<0...99> = 5
when System.screen.frame
  if System.keyboard.space.pressed then
    age = 0
  else
    age = age +| 1
  end
end
System.screen.text[0][0..<2] <- age.digits(2)

Notice how System.keyboard.space.pressed works right inside if ... then: an event used as a condition is true in the frames where it happens and false in all the others.

All events for a frame are decided in step 1, before any handler runs. That means when a handler changes a variable, that variable's .changed event fires at the start of the next frame, not midway through the current one.

If a handler stops the program—say, when a calculation steps outside its declared range—the variables it already changed keep their new values, and step 3 never updates the outputs.

Events

Every event has the type Event, or Event of T when it carries a value of type T each time it happens, as Types describes. You can give an event a name with a <- binding, so it stays live across frames, whereas storing an event in a constant or a var is caught with eventConstant.

Other events belong to individual devices and queues: shown on a screen region or a canvas, System.keyboard.dropped, and a queue's dropped and completed. The System Device Tree describes each device's events in full.

Start

start fires once, in the very first frame of the program. Inside a case, start fires in the first frame of that case each time the case begins. A when start handler is the natural home for a scripted sequence of steps paced with wait:

var ready: bool = false
when start
  wait(seconds: 2)
  ready = true
end
System.screen.border <- if ready then Color.green else Color.black end

Used inside an expression, start is true during the first frame of the program (or of its enclosing case) and false thereafter. Inside an op, start is also true in a frame where a reset: event starts the op over from the beginning, as Declarations describes.

Frame Events

System.screen.frame is the steady heartbeat of the machine: it happens in every single frame, including the first. System.screen.frame.every(n) ticks on every nth frame after the first—so every(3) happens in the fourth frame, the seventh, the tenth, and so on.

var x: Number<0...296> = 136
when System.screen.frame
  x = x +| System.joystick[2].dx
end
System.screen.sprite[0] <- (x: x, y: 170)

Presses and Releases

pressed fires in the exact frame a key or button goes down, and released fires in the frame it springs back up. Holding the key or button down across later frames does not fire pressed again. Every key on System.keyboard, a key chosen while the program runs with System.keyboard[key], the fire button of each joystick, and the left and right buttons of the mouse all provide both events.

var key: Key = .a
var presses: Number<0...99> = 0
when System.keyboard[key].pressed or System.mouse.left.pressed
  presses = presses +| 1
end
when System.joystick[2].fire.released
  key = .b
end

A value that is not a key or a button—such as a binding or a joystick's dx—has no pressed event; watch it with changed instead.

Changes

value.changed happens in any frame where a named value differs from what it was in the frame before. You can attach .changed to a variable, a binding, a struct field, or a device reading of any type.

var lives: Number<0...3> = 3
var over: bool = false
when System.keyboard.space.pressed
  lives = lives -| 1
end
when lives.changed when lives == 0
  over = true
end
System.screen.border <- if over then Color.red else Color.black end

A device reading changes in the frame the machine reads its new state. A variable that a handler modifies shows its .changed event in the next frame, because the frame's events are all decided before any handler runs. changed itself carries no value; simply read the value by name inside your handler.

Events That Carry a Value

Some events arrive bearing a gift: System.keyboard.stroke carries a Keystroke, and a queue's batch carries a list. Write when name = event to catch the carried value and give it a name inside the handler:

var shown: Char = .space
when s = System.keyboard.stroke
  if c = s.character() then
    shown = c
  end
end
System.screen.text[12][20] <- shown

You can also pack your own value onto any event with value when event, which creates a new event that carries value in each frame where event happens. The right side of when may even be a yes-or-no value, in which case the event happens in every frame where that condition is true.

points <- 2 when System.keyboard.space.pressed
var score: Number<0...99> = 0
when p = points
  score = score +| p
end
System.screen.text[0][0..<2] <- score.digits(2)

If an event carries no value, there is nothing to catch, so the compiler flags when name = on a valueless event with eventNoValue.

A stored optional (T?) is a value in memory rather than an event, even though it may hold something: writing when h = held triggers onNeedsEvent, and writing held when e triggers whenSubject. To react when an optional changes, watch held.changed, and inside the handler unwrap it with if h = held then.

Filters

Writing event when condition narrows an event so it happens only in the frames where event happens and condition holds true. The condition can be a yes-or-no expression, or another event (which counts as true in the frames where it fires). You filter a when handler the exact same way, by placing a second when after its event:

var shots: Number<0...99> = 0
var lives: Number<0...3> = 3
when System.keyboard.space.pressed when lives > 0
  shots = shots +| 1
end
moving <- System.screen.frame when System.joystick[2].fire
when moving
  lives = lives -| 1
end

When a handler names a carried value, its when filter can inspect that name right on the header line:

var plain: Key = .space
when s = System.keyboard.stroke when not s.shift
  plain = s.key
end

Keep using when to attach a filter to a handler line; if you write and instead, as in when s = System.keyboard.stroke and s.shift, the compiler nudges you with andOnLine.

filtered-event ::= expression 'when' expression
joined-event   ::= expression 'or' expression

Joined Events

a or b combines two events into one that happens in every frame where either a or b happens. If both events carry values of the exact same type, the joined event carries that type too, and when both happen in the same frame, the left-hand value wins. If only one carries a value, or their types differ, the joined event carries nothing.

left <- 1 when System.keyboard.a.pressed
right <- 2 when System.keyboard.d.pressed
var moved: Number<0...2> = 0
when step = (left or right)
  moved = step
end

In when name = ..., the name captures only the expression after = up to the first or, and, or when. Writing when step = left or right without parentheses would leave step empty whenever right happened alone, so the compiler catches it with orAfterAssignment; wrapping (left or right) in parentheses joins the two value-carrying events first.

Events and Conditions

Events and yes-or-no (bool) values are distinct kinds of things, and the compiler keeps them from getting tangled in and, or, and not:

• or joins either two events or two yes-or-no values; mixing one of each raises orNeedsEvents.
• and works on yes-or-no values, never on events (andEvents); to require two events in the same frame, filter one by the other with when.
• not flips a yes-or-no value and cannot be applied directly to an event (notEvent).

You can always turn an event into a yes-or-no test by comparing it with nil: event == nil is true in frames where the event stays quiet, and event != nil is true in frames where it happens.

Event Members

Event members have built-in memory across frames—counting presses, cycling through colors, or keeping a running tally—so each one lives in a <- binding where it can keep its own state from frame to frame. Most belong to an event, while sum, sampled, and history can also watch a changing value in every frame. If you place one inside a handler, where it would be forgotten at the end of the block, the compiler catches it with memoryOutsideBinding. By contrast, .changed, .pressed, and .released are maintained once by their source, and every reader shares them freely.

press <- System.joystick[2].fire.pressed
third <- press.every(3)
presses <- press.count(0...255)
shade <- third.cycle(Color)
bat <- (System.joystick[2].dx * 4).sum(from: 136, in: 0...296)
System.screen.border <- shade
System.screen.sprite[0] <- (x: bat, y: 170)

Ranges and Periods

cycle, count, countdown, and sum can take their range either from an inline range argument—such as e.cycle(0..<4), e.count(in: 0...99), or x.sum(from: 136, in: 0...296)—or from the type annotation on the binding that holds them. Passing the range inline lets you chain .cycle(0..<4) directly inside a larger expression like palette[System.screen.frame.every(6).cycle(0..<4)]. e.countdown(from: k) defaults its range to 0...K when k has a known non-negative upper bound K, so hit.countdown(from: 6) > 0 needs no extra range annotation. If neither an inline range nor a binding type supplies the bounds, the compiler reminds you with timeNeedsRange.

cycle steps through whole numbers or an enum, so giving it a fractional range raises wrongType. When a count climbs past the top of its range, the program stops and names the line; sum clamps gently to the nearer end of its range instead. sum adds numbers in every frame—or adds the numeric values carried by an event in the frames where it happens—and flags non-numeric inputs with sumNeedsNumber. latest remembers the last value an event carried, so calling it on an event that carries nothing raises timePayload.

The period n in every(n) is a whole number from 1 to 65,535 and may vary while the program runs. The frame count n in after(n) (0 to 65,535) and in hold(n) or cooldown(n) (1 to 65,535) is a constant whole number; all four also accept frames:, seconds:, or ms: labels. Any period or delay outside those bounds is caught with timePeriod. If e happens again before e.after(n) has delivered its delayed tick, the new occurrence replaces the waiting one and starts the n-frame countdown fresh. On any yes-or-no expression b, b.rising (or b.rising()) fires in the frames where b becomes true after being false on the prior frame, and b.falling (or b.falling()) fires when b becomes false after being true.

You can also pace sum and history with an event: x.sum(on: e) adds x only in the frames where e happens, and x.history(n, on: e) records a fresh sample only in those frames.

Resetting a Member

Every stateful event member accepts reset:, an event that snaps the member back to its starting value. When both the reset event and an update happen in the same frame, the reset wins.

step: Number<0...7> <- System.screen.frame.every(4).cycle(reset: System.keyboard.space.pressed)
System.screen.border <- Color(step)

Guard

guard condition checks that a requirement holds before letting the handler continue. When the condition is false, the handler stops for this frame: none of the statements below the guard run, any enclosing forever loop stops as well, and the handler simply waits to start from the top on its next event.

guard-statement ::= 'guard' expression
                  | 'guard' name '=' expression ( 'and' expression )?

guard name = optional unwraps an optional value for the rest of the handler when it is present, or ends the handler on the spot when it is nil. You can chain and right after the unwrap to test a condition that reads the newly named value:

var held: Number<u8>? = nil
var shown: Number<u8> = 0
when System.keyboard.space.pressed
  guard h = held and h > 3
  shown = h
end
when System.keyboard.h.pressed
  held = 7
end

A single guard line can name one optional value; adding a second = on the same line is caught with secondAssignment. Because functions, ops, and bindings must always produce a value rather than stopping early, placing a guard inside them raises guardOutsideHandler.

Wait

wait pauses a handler right where it stands. The handler rests for the remainder of the current frame and picks up on a later frame right after the wait, with all of its local variables still holding the values you left in them.

wait-statement ::= 'wait' '(' expression ')'
                 | 'wait' '(' time-unit ':' expression ')'
                 | 'wait' expression
time-unit      ::= 'seconds' | 'ms'

enum Scene
  case title, game
end
var scene: Scene = .title
var credit: bool = false
match scene
  title ->
    System.screen.text[10][17..<22] <- "ADDER"
    System.screen.text[12][13..<26] <- if credit then "A GAME BY YOU" else "             " end
    when start
      wait(100)
      credit = true
      wait System.joystick[2].fire.pressed
      scene = .game
    end
  game ->
    System.screen.text[11][16..<23] <- "GAME ON"
end

While a handler is paused at a wait, its own trigger event goes unheard: if a when ...pressed handler is mid-wait when the player presses that button again, the extra press passes by and is not saved up for later. In any single frame, a waiting handler runs only the stretch of statements between one wait and the next; Costs and the Frame explains how the compiler budgets each stretch.

wait belongs strictly inside a handler. Functions, work members, and bindings compute their answers immediately, so placing a wait or forever inside them raises waitOutsideHandler.

Waiting for Frames

wait(n) pauses for n frames, where n is a whole number from 1 to 65,535. The count n can come from a variable or calculation, as long as its type range starts at 1 or higher. Since a wait must always yield for at least one frame, the compiler flags wait(0) with waitNoFrames, a count whose range includes 0 with waitMayNotPause, and anything other than a whole number or event with waitNeedsEventOrFrames.

Because PAL and NTSC machines tick at different frame rates, a raw frame count runs at the machine's native speed: wait(100) lasts 2 seconds on PAL (50 Hz) and about 1.7 seconds on NTSC (60 Hz).

Waiting for a Time

When you want a pause to feel the same on every television standard, write wait(seconds: t) or wait(ms: t). The compiler converts your time into the nearest whole number of frames for each standard—always at least 1 frame—so the pause is accurate to within half a frame everywhere.

The duration t must be a constant greater than zero, written with either seconds: or ms:. The compiler catches a variable or non-positive time with waitTimeAmount, unknown or doubled unit labels with waitTimeUnit, and a duration that exceeds 65,535 frames on any machine with waitTimeLong.

var lit: bool = false
when start
  forever
    wait(ms: 500)
    lit = not lit
  end
end
System.screen.border <- if lit then Color.white else Color.black end

Waiting for an Event

wait event pauses the handler until event happens in a later frame. You can wait on any event, including one built with when filters or joined with or. Passing a plain yes-or-no value instead of an event raises waitNeedsEventOrFrames.

var go: bool = false
when start
  wait System.keyboard.a.pressed or System.joystick[2].fire.pressed
  go = true
end

Remember that the machine decides all of a frame's events at the very top of the frame, before any handler runs. Because of that, the event in a wait cannot depend on a name created inside the handler—such as a local var, a for loop counter, or a carried event value—and the compiler flags such references with waitEventReadsLocal.

Waiting for a Timer

A System.clock.timer(...) fires once after its countdown from the start of the program or case, and never fires a second time. To make sure your handler is guaranteed to be listening before the timer goes off, the compiler accepts wait timer only inside a when start handler of the same program or case that declared the timer, outside any forever or for loop, and before any open-ended event wait or any timed wait as long as the timer itself:

ready <- System.clock.timer(seconds: 2)
var go: bool = false
when start
  wait ready
  go = true
end

Whenever one of those rules triggers, the compiler message suggests a direct timed wait such as wait(seconds: 2). Waiting on timer or another event is allowed anywhere, because the other event can always wake the handler even if the timer has already passed. If you want a recurring beat you can wait on again and again, use System.clock.interval(...) instead.

Forever

forever repeats its body over and over for as long as its handler stays active. Inside a case, it loops until the case ends; at the top of the program, it loops until the program stops.

forever-statement ::= 'forever' newline statement* 'end'

Because a handler must yield back to the frame after each stretch of work, every trip around a forever loop must hit a wait on every possible path through its branches. If there is any path through the loop that could spin back to the top without waiting, the compiler catches it with foreverNeverWaits and points out the path that stayed awake.

break is for bounded for loops and cannot be used to jump out of a forever (breakInForever). To stop a forever loop, either end the whole handler with guard or switch to another case. A for loop has a fixed number of turns, so it does not require a wait, though you are welcome to put a wait inside one when you want to pace its steps across frames.

Handlers in a Case

A case's handlers start from the top when it starts matching and stop, waiting ones included, when it stops matching. Declarations in a Match describes the rule and its scope.

Queues

A queue is a first-in, first-out line of items: handlers drop items in the back, and your program takes them from the front in the order they arrived. Declare one at the top level with Queue(of: T, capacity: n), giving it a constant name, an item type T, and a maximum capacity from 1 to 65,535.

queue-declaration ::= name '=' 'Queue' '(' 'of' ':' type ',' 'capacity' ':' expression ')'

A queue provides four members:

• add(item), used as a statement inside a handler, places a new item at the back of the queue;
• take(on: System.screen.frame, limit: n), used in a single binding, is an event that fires when the queue is non-empty and carries a list of n optional items, oldest first, padded with nil in any slots it could not fill;
• count() gives the number of items currently waiting in line;
• dropped is an event that happens in the frame after a full queue had to turn away an add.

const deliveries = Queue(of: Number<u8>, capacity: 4)
var received: Number<0...999> = 0
var full_turns: Number<0...999> = 0
when System.keyboard.space.pressed
  deliveries.add(10)
  deliveries.add(20)
  deliveries.add(30)
end
batch <- deliveries.take(on: System.screen.frame, limit: 1)
when items = batch
  if amount = items[0] then
    received = received +| amount
  end
end
when deliveries.dropped
  full_turns = full_turns +| 1
end
System.screen.text[0][0..<3] <- received.digits(3)

Items added by a handler become available to take starting in the next frame. When the queue is empty, take stays quiet and its event does not happen. If a handler calls add when the queue is already at capacity, the newest item is turned away and dropped fires once in the following frame, no matter how many extra items were rejected during that frame.

Only one binding may call take on a given queue—any other readers simply read that binding's name, and a second take on the same queue is caught with queueConsumer. The compiler checks the remaining queue rules under queueForm: a queue must be a constant rather than a var, its capacity must stay within 1 to 65,535, take must live in a binding with on: System.screen.frame and limit:, add must be called inside a handler, and the item type T cannot itself be an optional (since take uses nil to mark empty slots in a batch—wrap an optional inside a struct if an item needs a missing-value state).

Queues of Jobs

A job queue, declared as Queue(of: Job of T, capacity: n), runs background work jobs one after another using the cycles left over in each frame after handlers and outputs finish. Call add(job) in a handler to enqueue a job, such as a call to a work member. As each job finishes, the queue's completed event fires (at most once per frame) carrying that job's result of type T, while dropped reports an overflow just like any other queue. Because the machine drains and runs a job queue automatically, you never call take on one (jobForm). Declarations shows how to write work members and jobs.

type Samples = [4 of Number<u8>]
work Samples.tally(input: Samples): Number<u16>
  var amount: Number<u16> = 0
  for sample in input
    amount = amount + sample
  end
  amount
end
const samples: Samples = [1, 2, 3, 4]
const jobs = Queue(of: Job of Number<u16>, capacity: 2)
var last: Number<u16> = 0
when System.keyboard.space.pressed
  jobs.add(samples.tally())
end
when result = jobs.completed
  last = result
end

Statements

Bindings describe how values flow continuously, while statements are the step-by-step instructions that change state or choose what happens next. Statements live inside the bodies of when handlers, inside mut fn member functions, and inside the for loops of ordinary functions. They run in a straight line from top to bottom, and each statement immediately sees the changes made by the statements above it.

statement       ::= assignment | local-variable | if-statement | match-statement
                  | for-loop | break-statement | call-statement

A handler body can also use guard, wait, and forever (see Events and Handlers), as well as asm blocks (see Assembly). The top level of a program holds declarations and handlers. An if there holds declarations with case lifetimes; inside a handler it holds statements. A loose for still needs a handler (loopAtTopLevel).

Assignment

An assignment stores a fresh value into a place in memory—whether that place is a whole variable, a single element of a list, a field of a struct, or a multi-element window of a list. Write the destination place on the left of = and the new value on the right.

assignment      ::= place '=' expression newline
place           ::= name selector*
selector        ::= '.' name | '[' expression ( ',' expression )? ']'

The machine evaluates the entire right-hand expression first and then stores the result into the place on the left. The new value must match the place's type (wrongType), and a constant literal that falls outside the place's declared range is caught right away with literalDoesNotFit. When the right-hand side is a calculation whose exact range the compiler cannot prove ahead of time, the program checks the number as it stores it. If the value steps out of range at runtime, the program halts and prints the offending line number on screen, as Values Outside a Range describes.

var lives: Number<0...3> = 3
var score: Number<0...999> = 0
when System.keyboard.space.pressed
  score = score +| 10
  lives = lives -| 1
end
System.screen.text[0][0..<3] <- score.digits(3)

Every assignment takes effect the moment it runs. In the handler below, the second line reads the updated value that the first line just stored:

var taps: Number<0...9> = 0
when System.keyboard.space.pressed
  taps = taps +% 1
  taps = taps +% 1
end
System.screen.text[0][0..<1] <- taps.digits(1)

Adder has a single assignment symbol, =, so every change is spelled out explicitly. Shorthand operators like x += 1 are flagged with actionNeeded—write x = x + 1 (or +% / +|) instead. And if you accidentally assign a variable to itself (x = x), the compiler points out the no-op with selfAssignment.

Elements, Fields and Windows

A place on the left of = can drill into a list element with [index], a struct field with .field, or a chain of both in any order. Only that selected part of the variable changes; the rest of the list or struct stays untouched.

struct Spot(x: Number<0...319>, y: Number<0...199>)
var spot: Spot = (x: 0, y: 0)
var spots: [4 of Spot] = Spot(x: 0, y: 0)
var grid: [3 of [4 of Number<u8>]] = 0
when System.keyboard.space.pressed
  spot.x = 10
  spots[2].y = 5
  grid[1][2] = 7
  grid[0] = [1, 2, 3, 4]
end

If an index is known at compile time to fall outside the list, the compiler catches it early with indexOutOfBounds. When an index varies at runtime, the program checks it before writing and halts with the line number if it ever steps out of bounds.

You can also index a list with a range to select a contiguous window of elements, or with two ranges to select a 2D rectangle inside a list of rows, just as in Expressions. Assigning to a window replaces all of its elements at once with a list of the exact same length. Because the right-hand side is read in full before any element is written, you can safely shift a slice of a list onto an overlapping window of the very same list:

var row: [8 of Number<u8>] = 0
var grid: [3 of [4 of Number<u8>]] = 0
var left: Number<0...4> = 0
when System.keyboard.space.pressed
  row[left..<(left + 4)] = [9, 9, 9, 9]
  row[0...3] = row[1...4]
  grid[0..<2, 1..<3] = [[1, 2], [3, 4]]
end

If the list on the right does not match the window's size, the compiler catches the mismatch with wrongLength.

Places That Cannot Be Assigned

Only a var variable—or a field, element, or window inside one—can receive a new value with =. Constants and <- bindings are fixed rules rather than storage boxes, so assigning to either is flagged with notAssignable.

Hardware outputs such as System.screen.border always take their values from a top-level or case-level <- binding, never from a statement inside a handler. Writing System.screen.border = .red inside a handler raises notAssignable, and writing System.screen.border <- .red inside a handler raises actionNeeded. To change what an output shows when an event happens, have the handler update a var and wire the output's binding to read that variable:

var alarm: bool = false
when System.keyboard.space.pressed
  alarm = not alarm
end
System.screen.border <- if alarm then .red else .black end

Every variable must be declared with var before you assign to it. Assigning to an undeclared name raises assignUndeclared, which keeps a typo on the left of = from silently inventing a brand-new variable.

Likewise, a hardware register declared with at is driven by a <- binding rather than assigned in a handler: assigning to one raises registerAssigned (or hardwareBound when it already has a binding). Declarations shows how placed hardware registers work.

Local Variables

Inside a handler, function, or loop, you can declare a temporary working variable with var. A local var always starts with an initial value after =, and may optionally include a : Type annotation.

local-variable  ::= 'var' name ( ':' type )? '=' expression newline

A local variable is visible from the line that declares it down to the end of its enclosing block—whether that block is the whole handler, one branch of an if, one case of a match, or the body of a for loop. Each time that block runs, the local variable starts fresh with its initial value.

var best: Number<0...9> = 0
when System.keyboard.space.pressed
  var steps: Number<0...9> = 0
  for i in 0..<3
    steps = steps +| 4
  end
  best = steps
end
System.screen.text[0][0..<1] <- best.digits(1)

To keep every name unambiguous on the page, a local variable cannot reuse a name that is already in view in an outer scope (shadowing). And once a block closes with end, its local variables go out of view; referring to one after its block ends raises unknownName.

If Statements

An if statement tests one or more conditions in order and runs the first branch whose condition holds true. Each condition is followed by then, and the entire if closes with a single end.

if-statement    ::= 'if' condition 'then' newline statement* else-branch? 'end' newline
                  | 'if' condition 'then' statement
                    ( 'else' 'if' condition 'then' statement )*
                    ( 'else' statement )? 'end' newline
else-branch     ::= 'else' 'if' condition 'then' newline statement* else-branch?
                  | 'else' newline statement*

Writing else if on one line continues the same if statement with another test, so a whole ladder of else if branches still needs only one end at the bottom. An else branch at the end catches the case where none of the conditions held true. When you leave else off and no condition is true, the if statement simply does nothing and execution moves on.

var level: Number<0...99> = 0
var shade: Color = .black
when System.keyboard.space.pressed
  level = level +% 7
  if level > 60 then
    shade = .red
  else if level > 30 then
    shade = .yellow
  else
    shade = .green
  end
end
System.screen.border <- shade

Note that if you put else on its own line and start a new if on the line below it, you have opened a nested if inside the else branch, and each if will want its own end.

Every if condition must evaluate to a bool (or an event, which acts as a bool for the current frame). The compiler catches a numeric condition with conditionNeedsBool, an unwrapped optional without = with bareOptional, and a missing then keyword with ifNeedsThen.

One-Line Form

For short, punchy decisions, you can place a statement right after then on the very same line. In this one-line form, the whole if—including any else if and else branches, each holding a single statement—stays on that one line and finishes with end.

var taps: Number<0...9> = 0
when System.keyboard.space.pressed
  if taps == 9 then taps = 0 else taps = taps + 1 end
end
System.screen.text[0][0..<1] <- taps.digits(1)

If a one-line if spills across a newline or tries to pack a for loop onto the line, the compiler flags it with inlineIfLine.

Conditional Names

An if condition can check whether an optional holds a value and unwrap it into a fresh name in a single step. Write if name = optional then: the branch runs only when optional is not nil, and inside that branch name holds the unwrapped value with its plain non-optional type.

condition       ::= expression | name '=' expression ( 'and' expression )?

Right after the unwrap, you can chain and with an extra test that uses the newly bound name. The machine evaluates the and test only when the optional was present, and runs the branch only when both succeed:

var held: Number<u8>? = nil
var shown: Number<u8> = 0
when System.keyboard.space.pressed
  held = 7
end
when System.keyboard.return.pressed
  if n = held and n > 3 then
    shown = n
  else
    shown = 0
  end
end
System.screen.text[0][0..<3] <- shown.digits(3)

The unwrapped name lives only inside the branch opened by that then—it is not in scope inside an else branch or after the if ends. (When you want an unwrapped name to stay in scope for the rest of a handler, reach for guard name = optional, as Events and Handlers describes.)

A conditional unwrap binds a single optional name and must stand at the very start of the condition. The compiler catches malformed unwraps with these messages:

Match Statements

A match statement compares a value against a list of patterns from top to bottom and runs the statements of the first case that fits. Each case writes its pattern, an optional when condition, an arrow ->, and the statements to run.

match-statement ::= 'match' expression newline match-case+ 'end' newline
                  | 'match' newline condition-case+ 'else' '->' case-body 'end' newline
match-case      ::= pattern ( 'when' expression )? '->' case-body
                  | 'else' '->' case-body
condition-case  ::= 'when' expression '->' case-body
case-body       ::= statement | newline statement*
pattern         ::= name | name '(' field-pattern ( ',' field-pattern )* ')'
                  | number | 'true' | 'false' | 'nil'
field-pattern   ::= name ( ':' name )?

You can put a single statement on the same line right after ->, or place a whole block of statements on the lines below ->. Leaving a case empty after -> is fine too—it simply does nothing when matched. Mixing both styles on the same case (putting a statement right after -> and more statements on the lines below it) is caught with statementAfterArm.

enum Mode
  case title, playing, over
end
var mode: Mode = .title
var lives: Number<0...3> = 3
when System.keyboard.space.pressed
  match mode
    title -> mode = .playing
    playing when lives == 0 -> mode = .over
    playing ->
      lives = lives - 1
    over ->
      lives = 3
      mode = .title
  end
end

A match used as an expression to compute a value uses the exact same pattern rules (see Expressions), while a match at the top of a program switches between cases (see Events and Handlers).

Patterns

Each pattern describes which values its case accepts:

• a bare case name from an enum or named set, such as title, matches that case;
• a case name with fields in parentheses, such as moving(grab, column: chosen), matches that case and unpacks its fields—either under each field's own name or under a local alias after :;
• a literal number, true, false, or nil matches that exact value;
• any other identifier matches every remaining value and gives it a name inside the case body (and when placed after a nil -> case on an optional, that name holds the unwrapped non-optional value);
• else matches every remaining value without naming it.

struct Spot(x: Number<0...319>, y: Number<0...199>)
enum Drag
  case still
  case moving(grab: Spot, column: Number<0...39>)
end
var drag: Drag = .still
var column: Number<0...39> = 0
var held: Number<u8>? = nil
var last: Number<u8> = 0
when System.screen.frame
  match drag
    moving(grab, column: chosen) ->
      column = chosen
      drag = .still
    still ->
  end
  match held
    nil -> last = 0
    value -> last = value
  end
end

Every Value Needs a Case

Every match must account for all possible values of the expression it tests. If any value is left unhandled, the compiler catches it with missingCoverage and lists the missing cases for you.

Because a when guard on a case might turn out to be false at runtime, a guarded case does not count as handling its pattern for all inputs—you still need an unguarded case (or else) below it. Conversely, writing a second unguarded case for a value that an earlier unguarded case already handled creates dead code, which the compiler flags with duplicateArm. And writing a nil case when the value being matched is not an optional raises nilArm.

Conditions on Cases

Adding when condition after a pattern narrows that case so it matches only when the pattern fits and the condition is true. The condition is free to read any names that the pattern unpacked. If the pattern fits but the when condition is false, the machine keeps scanning down to the remaining cases below.

var hits: Number<0...9> = 0
var shade: Color = .black
when System.keyboard.space.pressed
  hits = hits +% 1
  match hits
    0 -> shade = .black
    n when n > 5 -> shade = .red
    else -> shade = .green
  end
end
System.screen.border <- shade

Match Without a Value

Write match with nothing after it on the header line when you want a clean multi-way table of boolean conditions. Each arm starts with when condition ->, and the final arm is else ->, which runs if none of the conditions above it held true.

var level: Number<0...99> = 0
var shade: Color = .black
when System.keyboard.space.pressed
  level = level +% 9
  match
    when level > 60 -> shade = .red
    when level > 30 -> shade = .yellow
    else -> shade = .green
  end
end
System.screen.border <- shade

A valueless match always requires at least one when case and a closing else case; leaving either out raises conditionalMatch.

For Loops

A for loop steps through each number in a range or each element in a list from start to finish, running its body once per step. The loop variable named after for holds the current item on each turn.

for-loop        ::= 'for' name 'in' ( range | expression ) newline statement* 'end' newline
break-statement ::= 'break' newline

Over a Range

for i in 0..<8 runs eight turns with i counting from 0 through 7, while the inclusive range for i in 1...3 runs three turns with i counting from 1 through 3. Inside the loop body, i has the exact bounded type Number<low...high> of the range, which means you can use i to index into a list of matching size with zero runtime bounds checks. Both ends of a for range must be whole numbers known at compile time—literals, constants declared above, or parenthesized arithmetic on them, as Range Bounds describes.

const size = 8
var row: [size of Number<u8>] = 0
when System.keyboard.space.pressed
  for i in 0..<size
    row[i] = row[i] +% i
  end
end
System.screen.text[0][0..<3] <- row[7].digits(3)

The compiler flags a runtime-varying range bound with rangeEndNotFixed, a fractional bound with forRangeNeedsWhole, and an empty range (such as 5..<5 or 5...3) with rangeEmpty.

Over a List

for x in xs visits each element of the list xs in order from first to last, giving x the element type of the list. You can loop over a list variable, a list constant, a bracketed list literal, or any expression that produces a list.

var scores: [4 of Number<0...99>] = [3, 1, 4, 1]
var tally: Number<0...999> = 0
when System.keyboard.space.pressed
  tally = 0
  for s in scores
    tally = tally + s
  end
end
System.screen.text[0][0..<3] <- tally.digits(3)

Because for x in xs reads elements directly from xs as it walks through memory, the loop body cannot modify xs while iterating over it (loopListChanged). When you want to update a list's elements in place, loop over its indices instead—for i in 0..<n—and assign to xs[i].

Trying to run a for loop over something that is neither a range nor a list raises forNeedsList.

The Loop's Name

The loop itself advances its counter or element name at the start of every turn, so the body is not allowed to assign a new value to the loop variable (loopVariableSet). Like any other local variable, the loop's name cannot shadow an existing name in scope, and it disappears once the loop reaches end.

Break

break jumps out of the innermost for loop immediately, continuing execution at the first statement after that loop's end. You can place break inside an if or match within the loop body whenever you want to stop searching early.

var xs: [8 of Number<u8>] = [3, 1, 4, 0, 5, 9, 2, 6]
var before: Number<0...8> = 0
when System.keyboard.space.pressed
  before = 0
  for x in xs
    if x == 0 then break end
    before = before + 1
  end
end
System.screen.text[0][0..<1] <- before.digits(1)

Using break outside of any for loop raises breakOutsideLoop, and using break inside a forever loop raises breakInForever (since a forever loop is ended with guard or a case change instead).

Loops and the Frame

Unless a handler's for loop contains a wait, all of its turns run within a single television frame. The compiler adds up the worst-case cycle cost of the loop across all its turns and flags any loop that could overrun a PAL or NTSC frame budget with loopOverrun. Costs and the Frame explains how the compiler budgets loop cycles and how a work job can spread a heavy calculation across several frames.

An op computes a streaming signal expression every frame and cannot hold a for loop (loopInOp).

Calls and Device Actions

When a call stands on a line of its own as a statement, it performs an action: striking a note on a sound voice, moving a text cursor, adding an item to a list or queue, or running a mut fn method on a struct.

call-statement  ::= place '(' ( argument ( ',' argument )* )? ')' newline
argument        ::= ( name ':' )? expression

Here are the built-in statement actions and member calls:

const voice = System.sound[1].voice[1]
struct Score
  var points: Number<0...999> = 0
  mut fn award()
    points = points +| 10
  end
end
var score = Score()
when System.keyboard.space.pressed
  score.award()
  voice.play(Tone(.c4, decay: .short))
  System.screen.home()
  System.screen.print(score.points.digits(3))
end
when System.keyboard.space.released
  voice.release()
end

The System Device Tree describes each device's actions and arguments in detail. Device actions like striking a sound note happen only in response to an event, so calling play inside a pure function is caught with playOutsideOn.

Statements in Functions

An ordinary fn function computes and returns a value purely from the parameters you pass in. Inside its body you are free to declare local var variables and step through for loops to build up your answer, while your program's top-level variables and hardware devices stay safely off-limits—trying to assign to a program variable inside a function raises functionSets. Declarations describes function declarations in full.

At the outer level of a fn body, an if or match is an expression that produces the function's return value (see Expressions), which is why a top-level if in a function always needs an else branch. Inside a for loop within that function, however, if and match act as ordinary statements that update your local variables. Inside a fn body, const name = value introduces a fixed local calculation; its expression is evaluated when that line runs. Writing name = value updates an existing local var. A fixed local calculation cannot be reassigned and does not update automatically when its inputs change. Trying to assign a second time to a local constant is caught with localImmutable.

fn capped(xs: [4 of Number<u8>]): Number<u16>
  var kept: Number<u16> = 0
  for x in xs
    if x > 100 then
      kept = kept + 100
    else
      kept = kept + x
    end
  end
  kept
end
result <- capped([1, 2, 200, 4])
System.screen.text[0][0..<3] <- result.digits(3)

A mut fn member function on a struct is built for state changes from top to bottom: its entire body consists of statements, and it can freely update the fields of its struct.

The System Device Tree

Open the lid of the machine and you meet its working parts: the video chip painting the television screen, the three-voice sound synthesizer, the keyboard matrix, the control ports waiting for joysticks, paddles or a mouse, and the timers ticking away inside the interface chips. In Adder, every one of those parts lives at a clear, readable path under System—such as System.screen.border for the frame around the picture or System.joystick[2].fire for the red button on port 2. You write the full System path wherever you touch a part of the hardware (or give it a short nickname with a constant), and no variable you declare can accidentally shadow a device. This chapter tours the whole machine: every device, its members and their types, what happens when you read or bind each one, and what it costs in bytes and cycles when the cost report measures it.

device-path ::= 'System' ( '.' name | '[' expression ']' )*

Almost every member you meet on the device tree works in one of four ways:

The remaining members are makers: canvas(...) and region(...) carve out a pixel canvas or a text window on the screen, while System.clock.interval(...) and System.clock.timer(...) set up timed clock events. System.screen.interrupt(line:) and System.clock.interrupt(ms:) are events of a special breed: a when handler for either one is a hardware interrupt routine. To keep your logic steady from top to bottom, the program takes all of its hardware readings once at the very start of each frame, before any handler runs. See Outputs for how output bindings work, and Events and Handlers for everything you can do with events.

Paths

Devices With Numbers

Whenever the machine has more than one of the same unit—two joystick ports, two paddles on a plug, three voices on the sound chip—you pick the one you want with its hardware number in brackets, just like indexing a list. The two control ports on the side of the case are numbered 1 and 2, so the joysticks are System.joystick[1] and System.joystick[2]. If you leave the bracketed number off, the compiler reminds you with instanceNeeded; if you ask for a number the machine does not have, it catches that with noInstance and lists the valid numbers right in the message.

You do not have to hard-wire the number if you want the player to pick a port or cycle through voices on the fly: any variable whose range matches those exact numbers can sit inside the brackets. When a program picks a joystick through a variable this way, it samples both control ports every frame so either reading is ready on demand.

var port: Number<1...2> = 2
when System.keyboard.one.pressed
  port = 1
end
System.screen.border <- if System.joystick[port].fire then .red else .black end

Naming a Device

Typing System.joystick[2] over and over can wear out your fingers, so a top-level constant can give any device—or any branch of one—a short, friendly alias. Because a device is a physical place in the machine rather than data you can copy around, the compiler keeps you from storing a device in a variable, binding it as a value, putting it in a list, or passing it as a function argument (deviceNotValue).

const screen = System.screen
const stick = System.joystick[2]
screen.border <- if stick.fire then .red else .black end

Devices Not Built Yet

A few paths on the tree reserve spots for expansion hardware that Adder does not drive yet: System.sound[2] for a second SID chip, System.reu and System.georam for RAM expansion cartridges, and System.lightpen for a light pen. If you touch one of them today, the compiler lets you know with notBuilt and links no code for it.

The Screen

System.screen is your television display, driven by the VIC-II video chip. Here is everything hanging off System.screen:

The whole screen also acts as a text region in its own right, so it comes equipped with all the printing tools of a region: print, println, shown, cursor controls, and the rest.

Border and Background

border sets the color of the wide frame around the active picture, and background sets the paper color behind the characters. Without a binding, the machine greets you with its classic Commodore livery: a light blue border around a deep blue background. Want horizontal stripes of color down the screen? Color Bands shows how to tint individual raster ranges of either one.

var hue: Number<0...15> = 0
when System.keyboard.space.pressed
  hue = hue +% 1
end
System.screen.border <- Color(hue)
System.screen.background <- .black

In the cost report for this little program, the live border binding takes 20 bytes and at most 27 cycles per frame. The constant background <- .black line is set once at start-up: it takes 3 bytes of code and costs 0 cycles during the frame loop.

Text and Ink

text is the classic 25-row by 40-column character grid, where each cell holds one screen code. You can bind the whole 25-by-40 grid at once, a single row, a horizontal slice of a row, or a single cell, using the index and range forms from Expressions. Drop a string literal into a row slice of matching length and the compiler automatically translates its characters into screen codes for the active font. Both the row index and the starting column of a slice can move while the program runs; only the slice's width has to be fixed so the compiler knows how many cells to write.

var row: Number<0...24> = 12
when System.joystick[2].fire.pressed
  row = row +% 1
end
System.screen.text[row][15..<20] <- "ADDER"
System.screen.text[0][0] <- .block
System.screen.ink[row] <- .yellow

ink is the matching 25-by-40 grid of foreground colors—one color nibble for each character cell's lit pixels. Because a single value bound to a list fills every slot of that list, ink[row] <- .yellow paints an entire row yellow and ink <- .yellow paints every character on the screen. If you bind a list of values instead, its length has to match the target slice; if they disagree, the compiler points out the mismatch with wrongLength.

font selects the character set that shapes every cell on the text screen. By default, Adder starts in Charset.lowercase, which gives you both lowercase and capital letters; switching to Charset.uppercase gives you uppercase letters alongside the full suite of PETSCII box-drawing and card-suit graphics.

System.screen.font <- Charset.uppercase
System.screen.text[12][17..<22] <- "HELLO"

If you would rather place strings by row and column without counting out slice lengths by hand, see Text Placement.

Scroll and Window

scroll nudges the entire text grid and its colors smoothly by x pixels right and y pixels down, each from 0 to 7. Without a binding, the video chip rests at its normal home offset of (x: 0, y: 3). By feeding scroll from a variable and shifting characters by one cell whenever the pixel offset wraps past 7, you can build silky-smooth pixel scrolling.

columns and rows control the video chip's framing aperture. Switching to columns <- 38 and rows <- 24 pulls the border inward by a character width on the sides and a character height at the top and bottom (leaving pixels x 7 to 310 and y 4 to 195 visible), which neatly masks the seam where new characters pop in during a scroll. Each aperture setting takes one of its two fixed sizes, written as a constant in your program.

var shown_x: Number<0...255> = 0
System.screen.columns <- 38
System.screen.rows <- 24
System.screen.scroll <- (x: 7 - shown_x % 8, y: 3)
when System.screen.frame
  shown_x = shown_x +% 1
end

The runtime latches the new scroll values at the very top of the next frame while the beam is still in the border, so the picture never tears mid-screen. A constant scroll and a narrowed 38-column or 24-row window are configured once at start-up and cost 0 cycles per frame; a live scroll that changes at run time costs just two loads and two stores per frame. If you bind a changing scroll while leaving the screen at the full 40 columns or 25 rows, the cost report adds a friendly reminder on that line noting that the character seam will show at the edge and showing the exact columns <- 38 or rows <- 24 line that hides it. Plain border and background bands preserve a changing vertical scroll. Bands whose interrupt needs raster line 256 or later, authored assembly, custom interrupts and cases still cannot share that changing vertical scroll. Programs that display a bitmap canvas or cases with different text modes do not use scroll.

Frames and the Video Standard

System.screen.frame is the heartbeat of an Adder program: it fires once at the beginning of every television frame—50 times a second on a European (PAL) machine and 60 times a second on a North American (NTSC) machine. System.screen.frames is a 16-bit counter that ticks up from 0 on each frame and wraps cleanly from 65,535 back to 0.

When your program boots, it measures the video chip against the timer to see what kind of machine it is running on. standard reports what it found: 0 for PAL, 1 for standard NTSC, and 2 for the early 64-cycle-per-line NTSC video chip found in the earliest silver-label machines. frame_cycles gives you the exact processor cycle budget of one frame on that hardware: 19,656, 17,095, or 16,768. Both values are measured once at start-up and stay constant for the life of the run.

var ticks: Number<0...9> = 0
when System.screen.frame
  ticks = ticks +% 1
end
System.screen.border <- if System.screen.standard == 0 then .blue else .red end
System.screen.background <- Color(System.screen.frames % 16)
System.screen.text[0][0..<1] <- ticks.digits(1)

Color Bands

Want a sunset sky behind your title screen, a black status bar at the top, or a copper-style striped border? Putting a pixel-row range in brackets after border or background creates a color band that paints just those scanlines. Row 0 is the very first pixel row of the main 200-line picture window, so the picture itself runs from row 0 down to row 199. Because the border extends above and below the main window, a border band can also reach into rows -51 to -1 in the upper border and rows 200 to 210 in the lower border—the visible border rows shared by every PAL and NTSC machine. A background band stays within the main window, rows 0 to 199.

var hue: Number<0...15> = 0
when System.keyboard.space.pressed
  hue = hue +% 1
end
System.screen.border <- .blue
System.screen.border[-51..<0] <- .black
System.screen.border[49...98] <- Color(hue)
System.screen.background[96...199] <- .green

You write the band's vertical span as a single row or a range (a...b or a..<b) with constant endpoints known at compile time. The color expression on the right of <- can be as lively as you like; when it changes, the new color appears on those scanlines starting on the next frame. An unindexed binding on the same output (like System.screen.border <- .blue above) sets the base color for every row not claimed by a band; if you omit the base binding, unclaimed rows keep the machine's default startup color. Two bands on the same output cannot overlap on the same scanline.

To make sure every raster split fires cleanly on every television standard, the compiler checks your band ranges up front:

• if a band endpoint is a changing variable rather than a compile-time constant, it flags rangeEndNotFixed;
• if a row falls outside the valid range (-51...210 for border, 0...199 for background), it flags rasterSelection;
• if a border band reaches past row 210 into scanlines that only PAL televisions have, it flags rasterLine;
• if two bands on the same output share a scanline, it flags overlap.

Under the hood, each top and bottom edge of a color band is driven by a hardware raster interrupt: the video chip taps the processor on the shoulder at that exact scanline to swap the color register. In a program with a single border band, the cost report charges 67 bytes and 114 cycles per frame for the pair of interrupts. You can freely mix color bands with fixed-line interrupt routines—the compiler weaves them into a single sorted raster chain. However, a self-scheduling interrupt routine that writes its own raster lines needs full control of the raster interrupt vector (rasterOwner), and because bands use the hardware timer setup to stabilize their timing, they cannot share a program with a clock interval or timer (periodicOwnership).

Regions and Printing

A region is a rectangular window on the text screen with its own independent cursor, ink color, wrapping rules, and scrolling. System.screen itself is the root region spanning all 25 rows and 40 columns, and calling parent.region(row:, col:, width:, height:) carves out a sub-window inside any parent region.

All four geometry arguments are compile-time constants measured in character cells from the parent region's top-left corner. If you leave col out, it defaults to 0; if you leave width or height out, the region stretches to the right or bottom edge of its parent. The compiler checks your window layout at build time: if a region sticks out past its parent's edges, you get regionOutside, and if two sibling regions of the same parent claim the same character cell, you get regionOverlap.

const status = System.screen.region(row: 0, height: 1)
const log = System.screen.region(row: 1, height: 3, width: 12)
var entries: Number<0...999> = 0
status.text <- Text(row: 0, col: 0, content: "COUNT:")
when start
  log.cursor.ink = .light_green
end
when System.screen.frame.every(30)
  entries = entries +% 1
  log.println(entries.digits(3))
end

When you declare a region inside a case, it belongs to that case: it starts fresh and blank each time the case begins, and when the case finishes, whatever was on the screen underneath shows through again. See Events and Handlers for how cases work.

Region Members

Inside any when handler, you can update wrap, cursor.ink, and cursor.reverse with =, and your settings stay in effect for future prints until you change them again.

Printing

print and println accept any list of Char or ScreenCode values, including string literals. Adder never guesses how many digits or leading spaces you want for a number, so passing a bare number to print is caught with printList—just call .digits(n) on the number to format it into characters first.

diagonal <- ScreenCode(Number.random(77...78))
System.screen.font <- Charset.uppercase
when System.screen.frame
  System.screen.print([diagonal])
end

As characters stream into a region, a line that reaches the right edge wraps onto the row below. When the cursor is at the bottom row and needs a fresh line, the region scrolls its contents up by one row and blanks the new bottom line. Even better, a trailing newline at the very bottom of a region waits politely until the next character is actually printed before scrolling, so the last line you printed never scrolls off the top before the player can read it. In .word wrap mode, words that would cross the right margin hop down to the next row intact, while a single word wider than the entire region splits across rows. Strings hold visible characters rather than hidden control codes: use the explicit newline(), home(), and clear() actions whenever you want to move the cursor or wipe the window.

Every print formats its characters into the region's buffer right inside the handler that called it, during that same frame. The compiler calculates the worst-case cycle cost of the longest string that print can receive—including word wrapping and scrolling—and verifies that the frame budget can hold it, as explained in Costs and the Frame. If a large region takes more than one frame to copy its buffer out to the screen, you can trigger your next batch of output on shown to print as fast as the display can keep up:

when System.screen.shown
  System.screen.println("HELLO, WORLD!")
end

Partial region updates

partial before a region declaration permits its updates to appear one complete row at a time. Each row shown keeps characters and ink from the same captured state; a later print cannot change a waiting row. Other areas keep their whole-image promise.

partial const log = System.screen.region(row: 12, width: 8, height: 3)
when log.shown
  log.println("OK")
end

area-declaration ::= area-modifiers name '=' expression
area-modifiers   ::= 'partial' ( 'fast' | 'small' )?
                  | ( 'fast' | 'small' ) 'partial'

It combines with one fast or small preference, in either order. Plain printing regions with a fixed font use a private row, prepared in one frame and shown behind the beam in another. Shared colors and unmarked colored neighbors keep their existing updates; cases, overlapping layers and changing fonts retain their whole-image route. The cost report gives a shared showing bound after the final write; continuing writes can replace work. A hires partial canvas declared outside cases can show complete pixel rows and their cell colors while placed pictures change. Its row is captured before the following frame shows it; the report bounds when all its rows settle after the final change. An outline-only hires canvas keeps its ordinary resumable preparation in a private image, then captures the complete rows; its report includes the preparation and row-pass debt. A partial printing region using the default machine font beside a hires canvas with constant ink/paper and no drawing list also captures its logical characters and inks into a private glyph row, then shows that complete row at the following border. Its cursor, reverse, wrap and entered-line printing retain their ordinary meanings. An unmarked printing region in that fixed backdrop uses a real second bitmap and color matrix, keeps the old complete picture while rows are prepared, then switches the complete image at a border. It is refused with actual storage quantities when that second image cannot fit. Hidden catch-up after a flip does not keep the already complete visible region waiting. An unmarked default-font log can also share a whole hires picture with one root placed-picture engine and fixed ink/paper: each accepted drawing and captured log image finishes together while newer requests wait for the next picture. Source handlers keep running during hidden catch-up. Mixed picture/outline lists, multicolor canvases, canvases in cases and the remaining bitmap printing combinations still need their joined update paths and remain refused.

Text Placement

While print acts like a teletype cursor, Text(...) is for declarative labels and text boxes: it places characters at a given row and col, and binding it to System.screen.text (or a region's .text) keeps that text live on screen. You can also bind a list of Text(...) placements at once; if two placements overlap, a later item in the list paints over an earlier one.

var score: Number<0...999> = 0
when System.keyboard.space.pressed
  score = score +| 10
end
System.screen.text <- [
  Text(row: 2, col: 4, content: "SCORE"),
  Text(row: 2, col: 10, content: score.digits(3)),
]

Just as with print, a bare number is not content—use .digits(n) to turn it into characters first. To place several strings and values side by side on the same row without counting column offsets by hand, pass them as trailing positional arguments after row: and col: (or as a list in content: [...]). Each part is laid out immediately after the previous one's width, and any part can be wrapped in (part, ink: color) to give just those cells their own color while the rest use the placement's ink: (if any):

var score: Number<0...9999> = 42
System.screen.text <- Text(
  row: 0, col: 2, ink: .light_blue,
  "SCORE ", (score.digits(4), ink: .yellow),
)

The compiler checks the box geometry up front and flags textLayout if a placement's rectangle would spill off the screen, if you give a height without a width, or if you ask for overflow: .wrap without specifying both width and height.

A placement without a width is a label: it is simply as wide as its current content (clipped at the right edge of the screen). If a label's content shrinks—say, when a message changes from a long word to a short one—Adder automatically restores whatever characters lay underneath the vacated cells (or fills them with spaces). A placement with a width is a view: a rectangular box that holds its size steady as its content changes, padding any unused cells with spaces. By default a view clips at its right edge; with overflow: .wrap, long text flows onto the rows below inside the box. .word breaks lines cleanly at spaces between words, and .hyphenated also hyphenates any single word that is wider than the view itself.

When you omit ink:, Text touches only character cells and foreground colors come from your ink bindings. If a large multi-row layout takes more than a single frame to typeset and copy to the screen, Adder spreads the redraw across frames automatically, and if content changes again in the meantime, the newest layout cleanly supersedes any unfinished redraw.

Alignment and Justification

Two chainable methods let you align or justify text inside a view, returning a fresh placement without mutating the original: aligned(a) takes a TextAlignment—.leading, .center, or .trailing—and positions each line within the view's width. justified() spreads extra spaces evenly between words on every wrapped line that continues onto the row below (leaving the final line of a paragraph ragged, just like book typography); it requires .word or .hyphenated wrapping. If you chain more than one alignment or justification call on the same placement, the last one in the chain wins.

System.screen.text <- [
  Text(row: 0, col: 0, width: 16, content: "RADIO").aligned(.center),
  Text(row: 2, col: 0, width: 10, height: 2, overflow: .wrap,
       wrap: .word, content: "A B C LONGWORD").justified(),
]

Programs that use Text, TextWrap, TextAlignment, or region printing automatically link in Adder's text layout engine; programs that don't use them pay zero bytes for it.

Multicolor Text

Bind System.screen.multicolor to choose the two shared colors for the whole text screen. This switches the video chip into multicolor character mode. A cell with ordinary ink still uses hires pixels; .multicolor(color) selects pairs of horizontal pixels for that cell. Both choices take a color from the first eight palette colors (Color.black through Color.yellow), because the cell's color bit also records which choice it uses.

System.screen.multicolor <- (first: .green, second: .brown)
System.screen.text[0][0..<2] <- "AB"
System.screen.ink[0][0] <- .yellow
System.screen.ink[0][1] <- .multicolor(.yellow)

The shared colors may follow changing values and appear together at the frame border. A cell can choose hires or multicolor ink with if or a named binding. The compiler refuses a color outside the first eight for either choice. The whole-screen binding cannot be chosen separately inside a case until its text, ink, colors and mode can change together.

Calling System.screen.region(multicolor: true) also selects multicolor text for a region. Its ink uses the first eight colors; the compiler adds the cell's selection bit. Hires text beside that region keeps to the first eight colors too. A color from Color.orange through Color.light_grey is reported with multicolorInk or multicolorBeside, as appropriate.

const colors = System.screen.region(multicolor: true)
System.screen.text[10][14..<20] <- "COLORS"
System.screen.ink[10][14..<20] <- .yellow

Each case can display either multicolor text or a bitmap canvas, and a multicolor region declared inside a case applies only while that case is active.

Canvases

When character cells are not enough and you want to plot individual pixels, stamps, outlines, and tiled fills, a canvas switches the video chip into bitmapped graphics mode—320 pixels wide by 200 pixels tall. You declare one with System.screen.canvas(...) and bind its members through the constant name you give it.

const picture = System.screen.canvas()
const badge = Picture(["XXXXXXXX", "X......X", "X......X", "XXXXXXXX"])
x: Number<0...312> <- System.joystick[2].dx.sum(from: 80)
picture.ink <- .yellow
picture.paper <- .blue
picture.drawings <- [badge.place(x: x, y: 40)]
System.screen.sprite[0] <- (x: 160, y: 130, color: .white)

On a standard high-resolution (hires) canvas, each 8-by-8 pixel cell displays two colors: ink for lit (1) pixels and paper for clear (0) pixels. On a multicolor: true canvas, clear pixels show System.screen.background instead, so a multicolor canvas has no paper output—and conversely, a full hires canvas does not use System.screen.background. If you bind paper on a multicolor canvas or background on a hires canvas, the compiler points you to the right output with bitmapPaper or bitmapBackground.

Because the video chip uses the screen's memory for bitmap pixels, a canvas replaces the character grid where it sits. In a case with a full-screen canvas, touching System.screen.text or System.screen.font is flagged with bitmapText; if the canvas is a smaller window (row:, col:, width:, height:), touching System.screen.text alongside it is flagged with canvasText. A case can hold at most one canvas (canvasMore). A canvas declared at the top level of the program stays on screen for the whole run, while a canvas declared inside a case appears only while that case is active. Hardware sprites float right over a canvas just as they do over text.

const map = System.screen.canvas(row: 2, col: 10, width: 20, height: 12)
map.ink <- .green
map.paper <- .black

Pixel coordinates inside a canvas are always measured from the canvas's own top-left corner (0, 0), so the 20-cell-wide map canvas above is 160 pixels wide (x from 0 to 159). If a canvas's row, col, width, and height would push it past the 25-by-40 screen grid, the compiler catches it with canvasLeaves.

Drawings

drawings takes a list of drawing commands, rendered in list order so later items paint on top of earlier ones. Any slot in the list can evaluate to nil (giving the slot type Drawing?), and whenever a slot turns nil, the canvas cleanly erases that drawing and restores whatever was behind it. Helper functions can build and return drawings, and ++ concatenates lists of drawings together.

Outline Points count screen pixels relative to the canvas corner. Each endpoint is clipped to its canvas width and height before its screen position is added. On a multicolor canvas every x must be proved even, including later replacements of remembered Points; the last horizontal position is the left pixel of the final pair. Source Point lists and histories keep their local screen-pixel coordinates. | Text(content:, font:).place(x:, y:) | stamps a string using 8-by-8 character glyphs from a font at pixel (x, y) |

Both place and fill also accept flip: .horizontal or flip: .vertical to mirror the picture left-to-right or upside-down without storing a second copy of the art.

const picture = System.screen.canvas()
picture.ink <- .black
picture.paper <- .white
const corner = Picture(["XXXXXXXX", "X.......", "X.......", "X......."])
show <- System.joystick[2].fire
const box: [3 of Point] = [(x: 200, y: 20), (x: 300, y: 30), (x: 250, y: 90)]
picture.drawings <- [
  corner.place(x: 32, y: 32),
  corner.place(x: 64, y: 32, flip: .horizontal),
  Text(content: "SCORE").place(x: 16, y: 8),
  if show then box.outline().inverted() else nil end,
]

For Text(content:, font:).place(x:, y:) on a canvas, content is a string literal of 1 to 40 characters written right in the program. If you omit font:, it uses Charset.uppercase; you can also pass Charset.lowercase or a custom Charset(file:) loaded from your project folder. On a multicolor canvas, the font must also be created with multicolor: true.

Where a Drawing May Go

Inside a canvas, x counts pixels from the left edge and y counts pixel rows from the top. Every drawing must stay completely inside its canvas: for example, a 24-pixel-wide picture on a 320-pixel-wide canvas needs x between 0 and 296. If the compiler can see at build time that a coordinate is always out of bounds, it catches the mistake right away with placeRange. When the declared ranges of your x and y variables already prove that the drawing can never step off the canvas, the compiler emits zero bounds-checking code. If a variable's type is wider than the safe span (say, Number<u16>), the compiler inserts a tiny run-time bounds check that halts on that line if the drawing would ever leave the canvas—and the cost report notes both the check and how to narrow the variable's range (like x: Number<0...296>) to make the check disappear.

In video memory, each byte of a canvas holds 8 horizontal pixels. Whenever the compiler can prove from your expression that x lands on an 8-pixel byte boundary—such as a constant multiple of 8 or column * 8—it takes a fast byte-aligned path that copies bytes straight into the bitmap without shifting. For arbitrary pixel positions, it automatically pre-shifts or masks the art, and the cost report tells you which path each drawing line uses. On a multicolor canvas, pixels come in pairs, so x must be provably even (such as an even constant or column * 2). If a .fill(...) starts or ends partway through a byte, its width must be a compile-time constant so the edge masks are fixed (placeShifted).

When a Picture carries its own cell colors—such as Picture(art, ink: .red) or a multicolor picture with palette colors—stamping it also colors the 8-by-8 character cells underneath, so its vertical position y must be a multiple of 8 (placeCells).

Drawing Over Frames

You never have to manually erase old positions or flip double buffers on a canvas: Adder tracks what moved or changed since the last frame and redraws only the dirty rectangles. When a drawing moves or turns nil, the runtime automatically repairs the uncovered area from any drawings sitting underneath it, and clears any pixels no longer touched by any drawing. If a big case change or a large .fill(...) needs more cycles than a single frame can spare, the canvas renderer works incrementally across a few frames, pausing cleanly each frame so your handlers and sound never miss a beat.

The picture.shown event fires at the start of every frame in which the canvas is completely caught up—with no incremental drawing left in flight and no new changes pending. Updating your drawing positions inside when picture.shown lets an animation step forward as fast as the bitmap renderer can complete each frame:

const picture = System.screen.canvas()
const badge = Picture(["XXXXXXXX", "X......X", "X......X", "XXXXXXXX"])
var x: Number<0...304> = 0
when picture.shown
  x = if x == 296 then 0 else x + 8 end
end
picture.drawings <- [badge.place(x: x, y: 40)]

Sprites

The VIC-II video chip gives you eight independent hardware sprites—movable 24-by-21 pixel objects that float over text and bitmap canvases alike without disturbing a single byte of screen memory. System.screen.sprite is the list of all eight, numbered 0 through 7 (with sprite 0 drawn in front of sprite 1, and so on), and each slot takes a Sprite value.

Adder translates the video chip's raw hardware offsets for you so that (x: 0, y: 0) places the top-left corner of the sprite right at the top-left pixel of the 320-by-200 picture window. Because a standard sprite is 24 pixels wide and 21 pixels tall, keeping x in 0...296 and y in 0...179 keeps the whole sprite inside the main window, while negative coordinates let you slide a sprite smoothly in from the left or top border. Any sprite you do not bind stays switched off. Set behind: true to put a sprite behind text foreground pixels while leaving it in front of background pixels. In hires text, a glyph's set pixels are foreground. In multicolor text, the second shared color and the cell's own color are foreground; the background and first shared color stay behind the sprite. The priority changes at the frame border with the other sprite fields.

bat: Number<0...296> <- (System.joystick[2].dx * 4).sum(from: 136)
blink <- System.screen.frame.every(25).toggle()
System.screen.sprite[0] <- (x: bat, y: 170)
System.screen.sprite[1] <- (x: 40, y: 40, shown: blink, color: .yellow)

When you give a sprite a multicolor shape, its X pixels use that sprite's own color, while its A and B pixels use the two shared sprite multicolor registers that all multicolor sprites on screen share.

Sprites as a List

Instead of writing eight separate bindings, you can bind a constant range of sprites—such as System.screen.sprite[0..<4]—to a list of matching length, or bind System.screen.sprite itself to a list of all eight. Each hardware sprite takes the corresponding element from the list, and if the list holds optional Sprite? values, any slot that evaluates to nil switches that sprite off for the frame.

var xs: [4 of Number<0...296>] = [10, 70, 130, 190]
when System.joystick[2].fire.pressed
  xs[0] = xs[0] +% 8
end
System.screen.sprite[0..<4] <- xs.map(x -> Sprite(x: x, y: 50, color: .yellow))

Because each hardware sprite maps to specific VIC-II registers, the index or range in System.screen.sprite[...] must be a compile-time constant within 0...7 (spriteIndex). Each sprite can be bound only once at a given scope—whether individually or as part of a slice—so the compiler catches duplicate bindings with spriteBoundTwice and mismatched list lengths with spriteListLength. When you build a sprite list with .map(...), the compiler normally emits one compact loop that updates the sprites in turn; putting fast before the binding unrolls it into direct stores to each sprite's registers, spending a few extra bytes to shave off cycles.

The Keyboard

System.keyboard lets you test individual keys as live switches, process a buffered queue of typed keystrokes, or let the player type and edit a full input line:

All 64 key names on the Commodore keyboard matrix are listed in Named Sets.

Keys

Every key on the keyboard is a boolean reading that stays true for as long as the player holds that key down. Tack on .pressed to get an event that fires in the single frame the key goes down, or .released for the frame it springs back up.

var lives: Number<0...3> = 3
when System.keyboard.space.pressed
  lives = lives -| 1
end
System.screen.border <- if System.keyboard.left_shift then .red else .black end
System.screen.text[0][0..<1] <- lives.digits(1)