summaryrefslogtreecommitdiff
path: root/docs/chapter31
diff options
context:
space:
mode:
authorCliff Click <cliffc@acm.org>2026-08-10 11:11:18 -0700
committerCliff Click <cliffc@acm.org>2026-11-15 11:20:40 -0800
commit658289861e8d971cd9e449e66a749c9c2d65f623 (patch)
tree209a32ef7fab1d27222121bc8b53a968ff4b6796 /docs/chapter31
parent77ae05305a5653a2353709564705819f201e587f (diff)
downloadSimple-658289861e8d971cd9e449e66a749c9c2d65f623.tar.gz
Simple-658289861e8d971cd9e449e66a749c9c2d65f623.zip
Chapter 31: Software Drawing, Time, and Graphical Gameslinear
Co-authored-by: Hsiang-Ying Fu <66062782+fuhsnn@users.noreply.github.com> Co-authored-by: fuhsnn <66062782+fuhsnn@users.noreply.github.com> Co-authored-by: Symious <14933944+symious@users.noreply.github.com> Co-authored-by: Jun Kawasaki <jun784@gmail.com> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Diffstat (limited to 'docs/chapter31')
-rw-r--r--docs/chapter31/31-grammar.ja.md182
-rw-r--r--docs/chapter31/31-grammar.md273
-rw-r--r--docs/chapter31/README.ja.md25
-rw-r--r--docs/chapter31/README.md293
-rw-r--r--docs/chapter31/examples/A_helloWorld.smp2
-rw-r--r--docs/chapter31/examples/Breakout.smp369
-rw-r--r--docs/chapter31/examples/BubbleSort.smp38
-rw-r--r--docs/chapter31/examples/Capitalize.smp23
-rw-r--r--docs/chapter31/examples/Clock.smp128
-rw-r--r--docs/chapter31/examples/Dijkstra.smp71
-rw-r--r--docs/chapter31/examples/FileIO.smp52
-rw-r--r--docs/chapter31/examples/Graphics.smp26
-rw-r--r--docs/chapter31/examples/README.md119
-rw-r--r--docs/chapter31/examples/TicTacToe.smp132
-rw-r--r--docs/chapter31/examples/TicTacToeGraphical.smp169
15 files changed, 1902 insertions, 0 deletions
diff --git a/docs/chapter31/31-grammar.ja.md b/docs/chapter31/31-grammar.ja.md
new file mode 100644
index 00000000..eca363c1
--- /dev/null
+++ b/docs/chapter31/31-grammar.ja.md
@@ -0,0 +1,182 @@
+# 第31章の文法
+
+[English](31-grammar.md) | 日本語
+
+```antlrv4
+grammar SimpleLanguage;
+
+// Name lookup, assignable operands, type compatibility, and access permissions
+// are checked by the compiler in addition to these syntax rules.
+// A file is a compilation unit; its path supplies its namespace.
+// Qualified names resolve nested types and other units without an import keyword.
+program : statement* EOF ;
+
+block : '{' statement* '}' ;
+
+statement
+ : block
+ | returnStatement
+ | ifStatement
+ | whileStatement
+ | forStatement
+ | breakStatement
+ | continueStatement
+ | structDeclaration
+ | declaration ';'
+ | assignment ';'
+ | ';'
+ ;
+
+returnStatement : 'return' assignment ';' ;
+ifStatement : 'if' '(' assignment ')' statement ('else' statement)? ;
+whileStatement : 'while' '(' assignment ')' statement ;
+breakStatement : 'break' ';' ;
+continueStatement : 'continue' ';' ;
+
+forStatement
+ : 'for' '(' (declaration | assignment)? ';' assignment? ';' assignment? ')' statement
+ ;
+
+structDeclaration : 'struct' IDENTIFIER '{' structMember* '}' ';' ;
+structMember : constructorDeclaration | methodDeclaration | statement ;
+
+// The constructor name must match the enclosing struct's name.
+constructorDeclaration : 'new' IDENTIFIER '=' constructorExpression ';' ;
+constructorExpression : '{' constructorParameterList? '->' statement* '}' ;
+constructorParameterList : (constructorParameter ','?)+ ;
+constructorParameter : type '^'? bindingModifier? IDENTIFIER ;
+// ^ accepts an unfinished struct reference; ? independently permits null.
+// Only self may be read while incomplete; ^ arguments may be stored/forwarded.
+// A new result is incomplete iff an actual argument is. See ../../chapter29/README.md#incomplete-types.
+
+// A method is an ordinary fixed function binding in a struct definition.
+// The compiler supplies self; it is not written in parameterList.
+// Function types and expressions both receive their implicit receiver here.
+methodDeclaration : 'val' bindingModifier? IDENTIFIER '=' functionExpression ';' ;
+
+declaration : declarationType binding (',' binding)* ;
+declarationType : type | 'var' | 'val' ;
+binding : bindingModifier? IDENTIFIER ('=' initializer)? ;
+bindingModifier : '!' | '~' ;
+// A declaration initializer consisting of the string "C" declares an extern
+// symbol: a function, or explicit numeric native storage. Ordinary strings
+// elsewhere are array-valued expressions.
+initializer : assignment ;
+
+// The prefix qualifies the named struct reference, not an enclosing array.
+// Each [] / [~] suffix qualifies its own array layer. ? requires a reference.
+type
+ : functionType
+ | primitiveType typeSuffix*
+ | accessModifier? typeName typeSuffix*
+ ;
+accessModifier : '!' | '~' ;
+typeSuffix : '?' | '[]' | '[~]' ;
+typeName : IDENTIFIER ('.' IDENTIFIER)* ;
+
+primitiveType
+ : 'int' | 'i8' | 'i16' | 'i32' | 'i64'
+ | 'u1' | 'u8' | 'u16' | 'u32' | 'byte' | 'bool'
+ | 'flt' | 'f32' | 'f64'
+ ;
+
+assignment : expression (assignmentOperator assignment)? ;
+assignmentOperator
+ : '=' | '+=' | '-=' | '*=' | '/=' | '%=' | '&=' | '|=' | '^='
+ | '<<=' | '>>=' | '>>>='
+ ;
+
+expression : logicalExpression ('?' assignment (':' assignment)?)? ;
+
+// Both logical operators short-circuit and associate to the right here.
+logicalExpression : bitwiseExpression (('&&' | '||') logicalExpression)? ;
+
+bitwiseExpression
+ : equalityExpression (('&' | '|' | '^') equalityExpression)*
+ ;
+
+equalityExpression : comparisonExpression (('==' | '!=') comparisonExpression)* ;
+
+// Chained comparisons test adjacent operands and short-circuit. A chain must
+// keep its direction; equality has lower precedence and does not join a chain.
+comparisonExpression
+ : shiftExpression
+ ( (('<' | '<=') shiftExpression)+ | (('>' | '>=') shiftExpression)+ )?
+ ;
+
+shiftExpression
+ : additiveExpression (('<<' | '>>' | '>>>') additiveExpression)*
+ ;
+
+additiveExpression
+ : multiplicativeExpression (('+' | '-') multiplicativeExpression)*
+ ;
+
+multiplicativeExpression
+ : unaryExpression (('*' | '/' | '%') unaryExpression)*
+ ;
+
+unaryExpression
+ : ('-' | '!') unaryExpression
+ | updateOperator IDENTIFIER
+ | postfixExpression
+ ;
+
+// Prefix updates require a local name; postfix updates also allow fields
+// and array elements. All updates require an assignable operand.
+updateOperator : '++' | '--' ;
+postfixExpression : primaryExpression postfixSuffix* updateOperator? ;
+postfixSuffix : '.' IDENTIFIER | '[' assignment ']' | '#' | callSuffix | methodCallSuffix ;
+
+// For a fixed function-valued member, object.name(args) passes object as self.
+// This overlaps ordinary field selection followed by a call syntactically;
+// name/type resolution determines which call form applies.
+methodCallSuffix : '.' IDENTIFIER callSuffix ;
+
+primaryExpression
+ : INTEGER_LITERAL
+ | FLOAT_LITERAL
+ | STRING_LITERAL
+ | CHARACTER_LITERAL
+ | 'true'
+ | 'false'
+ | 'null'
+ | IDENTIFIER
+ | '(' assignment ')'
+ | newExpression
+ | functionExpression
+ ;
+
+// A function is an expression bound with an ordinary declaration.
+// Its last statement supplies the implicit result; return can exit earlier.
+functionExpression : '{' parameterList? '->' statement* '}' ;
+parameterList : (parameter ','?)+ ;
+parameter : type bindingModifier? IDENTIFIER ;
+
+// Function types have unnamed, space-separated argument types.
+// {int} is the zero-argument type; its function expression still uses ->.
+functionType
+ : '{' type+ '->' type '}' '?'?
+ | '{' type '}' '?'?
+ ;
+
+callSuffix : '(' argumentList? ')' ;
+argumentList : assignment (',' assignment)* ','? ;
+
+// Allocation invokes the declared constructor; inline initializer blocks from
+// earlier chapters are replaced by constructor arguments.
+newExpression : 'new' type ('[' assignment ']' | callSuffix)? ;
+
+INTEGER_LITERAL : [1-9] DIGIT* | '0' [0-7]* | '0' [xX] HEX_DIGIT+ ;
+FLOAT_LITERAL : DIGIT+ ('.' DIGIT* ('e' DIGIT+)? | 'e' '-'? DIGIT+) ;
+STRING_LITERAL : '"' (ESCAPE | ~["\\])* '"' ;
+CHARACTER_LITERAL : '\'' (ESCAPE | ~['\\]) '\'' ;
+fragment ESCAPE : '\\' [0ntr\\'"] ;
+IDENTIFIER : NON_DIGIT (NON_DIGIT | DIGIT)* ;
+fragment NON_DIGIT : [a-zA-Z_] ;
+fragment DIGIT : [0-9] ;
+fragment HEX_DIGIT : [0-9a-fA-F] ;
+WHITESPACE : [ \t\r\n]+ -> skip ;
+LINE_COMMENT : '//' ~[\r\n]* -> skip ;
+BLOCK_COMMENT : '/*' .*? '*/' -> skip ;
+```
diff --git a/docs/chapter31/31-grammar.md b/docs/chapter31/31-grammar.md
new file mode 100644
index 00000000..b1f563e4
--- /dev/null
+++ b/docs/chapter31/31-grammar.md
@@ -0,0 +1,273 @@
+# Grammar for Chapter 31
+
+English | [日本語](31-grammar.ja.md)
+
+The handwritten recursive-descent implementation lives in
+[`com.seaofnodes.simple.parser`](../../src/main/java/com/seaofnodes/simple/parser/).
+The production-to-code map below the grammar describes where syntax ends and
+name resolution or graph construction begins. This grammar documents the
+language; it is not input to a parser generator.
+
+`int` is an alias for `i32`; `i64` explicitly selects 64-bit integer storage.
+This alias does not change literal inference or intermediate arithmetic.
+
+Integer literals use decimal (`42`), leading-zero octal (`052`), or hexadecimal
+(`0x2a`, `0X2A`). Octal digits are 0–7; `08` and `09` are errors. Hexadecimal
+and octal literals can spell any 64-bit bit pattern: the high bit gives the
+usual signed value, so `0xffffffffffffffff` is -1. Decimal literals retain
+their signed 64-bit limit. Floating literals remain decimal, including forms
+such as `012.5` and `012f`. A radix prefix does not change integer inference
+or storage width.
+
+```antlrv4
+grammar SimpleLanguage;
+
+// Name lookup, assignable operands, type compatibility, and access permissions
+// are checked by the compiler in addition to these syntax rules.
+// A file is a compilation unit; its path supplies its namespace.
+// Qualified names resolve nested types and other units without an import keyword.
+program : statement* EOF ;
+
+block : '{' statement* '}' ;
+
+statement
+ : block
+ | returnStatement
+ | ifStatement
+ | whileStatement
+ | forStatement
+ | breakStatement
+ | continueStatement
+ | structDeclaration
+ | declaration ';'
+ | assignment ';'
+ | ';'
+ ;
+
+returnStatement : 'return' assignment ';' ;
+ifStatement : 'if' '(' assignment ')' statement ('else' statement)? ;
+whileStatement : 'while' '(' assignment ')' statement ;
+breakStatement : 'break' ';' ;
+continueStatement : 'continue' ';' ;
+
+forStatement
+ : 'for' '(' (declaration | assignment)? ';' assignment? ';' assignment? ')' statement
+ ;
+
+structDeclaration : 'struct' IDENTIFIER '{' structMember* '}' ';' ;
+structMember : constructorDeclaration | methodDeclaration | statement ;
+
+// The constructor name must match the enclosing struct's name.
+constructorDeclaration : 'new' IDENTIFIER '=' constructorExpression ';' ;
+constructorExpression : '{' constructorParameterList? '->' statement* '}' ;
+constructorParameterList : (constructorParameter ','?)+ ;
+constructorParameter : type '^'? bindingModifier? IDENTIFIER ;
+// ^ accepts an unfinished struct reference; ? independently permits null.
+// Only self may be read while incomplete; ^ arguments may be stored/forwarded.
+// A new result is incomplete iff an actual argument is. See ../../chapter29/README.md#incomplete-types.
+
+// A method is an ordinary fixed function binding in a struct definition.
+// The compiler supplies self; it is not written in parameterList.
+// Function types and expressions both receive their implicit receiver here.
+methodDeclaration : 'val' bindingModifier? memberName '=' functionExpression ';' ;
+memberName : IDENTIFIER | primitiveType ;
+
+declaration : declarationType binding (',' binding)* ;
+declarationType : type | 'var' | 'val' ;
+binding : bindingModifier? IDENTIFIER ('=' initializer)? ;
+// At class/struct member scope, memberName also permits primitive type names.
+// Ordinary locals and parameters still require a non-keyword IDENTIFIER.
+bindingModifier : '!' | '~' ;
+// A declaration initializer consisting of the string "C" declares an extern
+// symbol: a function, or explicit numeric native storage. Ordinary strings
+// elsewhere are array-valued expressions.
+initializer : assignment ;
+
+// The prefix qualifies the named struct reference, not an enclosing array.
+// Each [] / [~] suffix qualifies its own array layer. ? requires a reference.
+type
+ : functionType
+ | primitiveType typeSuffix*
+ | accessModifier? typeName typeSuffix*
+ ;
+accessModifier : '!' | '~' ;
+typeSuffix : '?' | '[]' | '[~]' ;
+typeName : IDENTIFIER ('.' IDENTIFIER)* ;
+
+primitiveType
+ : 'int' | 'i8' | 'i16' | 'i32' | 'i64'
+ | 'u1' | 'u8' | 'u16' | 'u32' | 'byte' | 'bool'
+ | 'flt' | 'f32' | 'f64'
+ ;
+
+assignment : expression (assignmentOperator assignment)? ;
+assignmentOperator
+ : '=' | '+=' | '-=' | '*=' | '/=' | '%=' | '&=' | '|=' | '^='
+ | '<<=' | '>>=' | '>>>='
+ ;
+
+expression : logicalExpression ('?' assignment (':' assignment)?)? ;
+
+// Both logical operators short-circuit and associate to the right here.
+logicalExpression : bitwiseExpression (('&&' | '||') logicalExpression)? ;
+
+bitwiseExpression
+ : equalityExpression (('&' | '|' | '^') equalityExpression)*
+ ;
+
+equalityExpression : comparisonExpression (('==' | '!=') comparisonExpression)* ;
+
+// Chained comparisons test adjacent operands and short-circuit. A chain must
+// keep its direction; equality has lower precedence and does not join a chain.
+comparisonExpression
+ : shiftExpression
+ ( (('<' | '<=') shiftExpression)+ | (('>' | '>=') shiftExpression)+ )?
+ ;
+
+shiftExpression
+ : additiveExpression (('<<' | '>>' | '>>>') additiveExpression)*
+ ;
+
+additiveExpression
+ : multiplicativeExpression (('+' | '-') multiplicativeExpression)*
+ ;
+
+multiplicativeExpression
+ : unaryExpression (('*' | '/' | '%') unaryExpression)*
+ ;
+
+unaryExpression
+ : ('-' | '!') unaryExpression
+ | updateOperator IDENTIFIER
+ | postfixExpression
+ ;
+
+// Prefix updates require a local name; postfix updates also allow fields
+// and array elements. All updates require an assignable operand.
+updateOperator : '++' | '--' ;
+postfixExpression : primaryExpression postfixSuffix* updateOperator? ;
+postfixSuffix : '.' memberName | '[' assignment ']' | '#' | callSuffix | methodCallSuffix ;
+
+// For a fixed function-valued member, object.name(args) passes object as self.
+// This overlaps ordinary field selection followed by a call syntactically;
+// name/type resolution determines which call form applies.
+methodCallSuffix : '.' memberName callSuffix ;
+
+primaryExpression
+ : INTEGER_LITERAL
+ | FLOAT_LITERAL
+ | stringExpression
+ | CHARACTER_LITERAL
+ | 'true'
+ | 'false'
+ | 'null'
+ | IDENTIFIER
+ | '(' assignment ')'
+ | newExpression
+ | functionExpression
+ ;
+
+// A function is an expression bound with an ordinary declaration.
+// Its last statement supplies the implicit result; return can exit earlier.
+functionExpression : '{' parameterList? '->' statement* '}' ;
+parameterList : (parameter ','?)+ ;
+parameter : type bindingModifier? IDENTIFIER ;
+
+// Function types have unnamed, space-separated argument types.
+// {int} is the zero-argument type; its function expression still uses ->.
+functionType
+ : '{' type+ '->' type '}' '?'?
+ | '{' type '}' '?'?
+ ;
+
+callSuffix : '(' argumentList? ')' ;
+argumentList : assignment (',' assignment)* ','? ;
+
+// Allocation invokes the declared constructor; inline initializer blocks from
+// earlier chapters are replaced by constructor arguments.
+newExpression
+ : 'new' type ('[' '~'? assignment ']' arrayInitializer? | arrayInitializer | callSuffix)?
+ ;
+// With no explicit length, type must end in [] or [~] and the initializer is a list.
+arrayInitializer
+ : '{' (assignment (',' assignment)* ','?)? '}'
+ | '{' ('int' | 'i32' | 'i64' | 'u32') IDENTIFIER '->' statement* '}'
+ ;
+
+INTEGER_LITERAL : [1-9] DIGIT* | '0' [0-7]* | '0' [xX] HEX_DIGIT+ ;
+// The f suffix also accepts an integer-shaped token, e.g. 12f.
+FLOAT_LITERAL : DIGIT+ ('.' DIGIT* ('e' DIGIT+)? | 'e' '-'? DIGIT+) 'f'?
+ | DIGIT+ 'f' ;
+// String text uses a lexical mode: whitespace/comments are literal here.
+// Interpolation re-enters the ordinary expression grammar, recursively.
+stringExpression : '"' (STRING_TEXT | ESCAPE | '%%' | interpolation)* '"' ;
+interpolation : '%' format? '(' assignment ')' ;
+format : FORMAT_FLAG* FORMAT_WIDTH? ('.' FORMAT_WIDTH?)? FORMAT_KIND TIME_STYLE? ;
+// Flags: - + space # 0. Width/precision: decimal digits, no expressions.
+// Kinds: d i u o x X f F e E g G a A c s b t.
+// TIME_STYLE: F r R M D T, allowed only after t; default F (ISO UTC).
+// Time styles: ISO, 12-hour, 24-hour, elapsed MM:SS.mmm, DD/MM/YY, HH:MM:SS.
+// Duplicate/inapplicable flags and precision on c/b/t are rejected.
+// Time accepts width and left alignment only; see time.md.
+// STRING_TEXT excludes double quote, backslash, and percent.
+CHARACTER_LITERAL : '\'' (ESCAPE | ~['\\]) '\'' ;
+fragment ESCAPE : '\\' [0ntr\\'"%] ;
+IDENTIFIER : NON_DIGIT (NON_DIGIT | DIGIT)* ;
+fragment NON_DIGIT : [a-zA-Z_] ;
+fragment DIGIT : [0-9] ;
+fragment HEX_DIGIT : [0-9a-fA-F] ;
+WHITESPACE : [ \t\r\n]+ -> skip ;
+LINE_COMMENT : '//' ~[\r\n]* -> skip ;
+BLOCK_COMMENT : '/*' .*? '*/' -> skip ;
+```
+
+## Reading the parser alongside the grammar
+
+All paths below are within `src/main/java/com/seaofnodes/simple/parser/`.
+The components share one `Parser` instance containing the cursor, active scope,
+compilation unit, and graph utilities. They are package-private collaborators;
+there is no inheritance chain, AST, or additional compiler pass.
+
+| Productions | Implementation |
+| --- | --- |
+| `program` | [`Parser.parse`](../../src/main/java/com/seaofnodes/simple/parser/Parser.java): establish the source-unit scope, parse its initializer, resolve remaining file names, publish its class |
+| `statement`, `block`, loops, jumps, `returnStatement` | [`Statements`](../../src/main/java/com/seaofnodes/simple/parser/Statements.java), starting at `parseStatement` |
+| `declaration`, `binding`, `bindingModifier` | [`Declarations`](../../src/main/java/com/seaofnodes/simple/parser/Declarations.java): declaration/expression lookahead, then each binding and initializer |
+| `structDeclaration`, `constructorDeclaration` | [`Structs`](../../src/main/java/com/seaofnodes/simple/parser/Structs.java), starting at `parseStruct` and `parseConstructorDeclaration`; field discovery and initialization checks follow these entry points |
+| `type`, `typeName`, `functionType` | [`Types`](../../src/main/java/com/seaofnodes/simple/parser/Types.java): `parseType` and `parseFunctionType`; qualified-name lookup lives in `typeName`, `dottedName`, and `rootedName` |
+| `assignment` through `primaryExpression` | [`Expressions`](../../src/main/java/com/seaofnodes/simple/parser/Expressions.java): `parseAssignment`, `parseExpression`, `parseLogical`, `parseBitwise`, `parseEquality`, `parseComparison`, `parseShift`, `parseAddition`, `parseMultiplication`, `parseUnary`, `parsePrimary` |
+| `postfixExpression`, member selection and updates | `Expressions.parsePostfix` / `parsePostfixMethod` dispatch to [`References.parseField`](../../src/main/java/com/seaofnodes/simple/parser/References.java); `References.parseName` handles bare names, implicit receivers, and forward references |
+| `functionExpression`, `parameterList`, calls, `argumentList` | [`Functions`](../../src/main/java/com/seaofnodes/simple/parser/Functions.java): `parseFunction`, `parseConstructor`, shared `parameters` and `arguments`, then `parseBody` |
+| `newExpression`, `arrayInitializer` | [`Allocations.parseNew`](../../src/main/java/com/seaofnodes/simple/parser/Allocations.java), [`ArrayInitializers`](../../src/main/java/com/seaofnodes/simple/parser/ArrayInitializers.java); private initialization, list checks, and generator loops |
+| `stringExpression`, `interpolation` | [`Strings.parse`](../../src/main/java/com/seaofnodes/simple/parser/Strings.java), using `Lexer.stringPart` / `stringFormat`; normal expression parsing resumes inside each interpolation |
+| Literals, identifiers, comments, token matching | [`Lexer`](../../src/main/java/com/seaofnodes/simple/parser/Lexer.java); it also supplies source-location snapshots used by diagnostics and serialized IR |
+
+`ControlFlow` shares guarded scope merging between `if`, `?:`, `&&`, and `||`.
+`Conversions` shares binding, field, and result conversions. These
+operations are compiler semantics rather than additional grammar productions.
+`Parser` retains the type registry and the small control/memory/peephole helpers
+used by several productions and by the rest of the compiler.
+
+There are a few deliberate differences between a syntax-only parser and this
+one-pass IR builder:
+
+- A statement beginning with `{` might be a block or a function-type binding.
+ `Declarations` and `Types` use speculative parsing and cursor restore;
+ qualified type lookup also stops before a suffix that belongs to an expression.
+- Bare assignment, field assignment, and compound updates share the grammar's
+ precedence but use different IR paths. `References` decides between an SSA
+ local, a constructor field's local value, and an actual memory access. A
+ function-valued field may also supply an implicit receiver to a call.
+- `for` updates are scanned first and parsed after the body, where their effects
+ belong. Explicit constructor bodies are scanned first and parsed after field
+ discovery, so later fields have local slots. Both use `Lexer.skipTo`, which
+ ignores delimiters inside comments and quoted text.
+- `Structs.parseInitializer` parses a file or struct body as a function while
+ discovering fields. `Functions.parseBody` still owns function scope/return
+ construction; moving it does not change constructor or memory semantics.
+
+The syntax chart does not describe all name/type restrictions. In particular,
+prefix updates require an already-known non-pointer binding, and a private-class
+privacy policy is separate from recognizing a qualified type name. The existing
+same-named function binding inside a struct is also recognized as a constructor;
+`new Name = { ... };` is the explicit constructor spelling above.
diff --git a/docs/chapter31/README.ja.md b/docs/chapter31/README.ja.md
new file mode 100644
index 00000000..511c72ee
--- /dev/null
+++ b/docs/chapter31/README.ja.md
@@ -0,0 +1,25 @@
+# 第31章:ソフトウェア描画とグラフィカルゲーム
+
+[English](README.md) | 日本語
+
+[前の章:第30章 — テキスト整形と診断](../chapter30/README.ja.md)
+
+第30章で完成したコンパイラと標準ライブラリを出発点とする章です。
+Simple で描画する `sys.draw.Canvas` と、MiniFB を使うオプションの
+ウィンドウ・入力 API `sys.gfx` を使って、グラフィカルな三目並べを実装します。
+矩形、円、太い線、色、ビットマップ文字を扱えます。
+詳細は[英語版の描画ライブラリとゲームの説明](../../src/main/smp/sys/draw/README.md)を参照してください。
+通常のビルドとテストに MiniFB や画面表示は必要ありません。
+
+```sh
+make -C chapter31 run-graphical-tictactoe
+```
+
+`%` は Java の `%` と同じ符号規則を使う剰余演算子です。`*`、`/` と同じ優先順位で、
+左から右に結合します。例えば `-17 % 5` は `-2`、`17 % -5` は `2` です。
+整数と浮動小数点数に対応し、整数のゼロ除算は Simple の `/` と同様にゼロを返します。
+詳しい意味と実装は[英語版の説明](README.md#remainder)を参照してください。
+
+このスナップショットの[文法](31-grammar.ja.md)と
+[実行可能な例](examples/)を用意しています。
+ビルド手順は[英語版](README.md)を参照してください。
diff --git a/docs/chapter31/README.md b/docs/chapter31/README.md
new file mode 100644
index 00000000..8debaf03
--- /dev/null
+++ b/docs/chapter31/README.md
@@ -0,0 +1,293 @@
+# Chapter 31: Software Drawing, Time, and Graphical Games
+
+[Previous: Chapter 30 — Text Formatting and Diagnostics](../chapter30/README.md)
+
+In this chapter we use small graphical games to drive the language and library
+work. We add graphics, sound, and time support, with a few small C adapters
+for native services. We also add array initializers and read-only arrays, hex,
+octal parsing, move constant arrays into the ELF constant pool. We then write
+a few games, with the drawing and game logic written in Simple.
+
+
+## Games and demos
+
+All graphical demos support resizing. Canvas scales their base layouts and
+mouse coordinates together, preserving proportions; Breakout's physics remains
+in base coordinates. The pixel gradient fills the resized window.
+
+[Clock](examples/Clock.smp) is a classic clock demo. It shows local time as
+digital digits or an analog dial. Click its button or press Space to switch
+views. It combines timers, mouse input, text, and drawing in one event loop.
+
+[Graphical Tic-tac-toe](examples/TicTacToeGraphical.smp) accepts mouse
+clicks or keys 1 through 9. It highlights the winning line and plays move and
+result sounds. Game logic is the same as in the terminal version from
+the prior chapter, with the graphics added to the event loop.
+
+[Breakout](examples/Breakout.smp) has a ball, a paddle, and a wall of
+bricks. Move the paddle with the arrow keys or mouse. The ball's bounce angle
+depends on where it hits the paddle. Deeper bricks score more points, make
+higher-pitched sounds, and increase the ball's speed. Hitting the *back* of a
+brick gives a one-time larger speed boost. Clear all the bricks before using
+up three balls.
+
+
+## Remainder
+
+`%` computes remainder with Java's sign convention. It has the same
+precedence as `*` and `/`, and associates left to right. For example,
+`17 % 5` is `2`, `-17 % 5` is `-2`, and `17 % -5` is `2`.
+The remainder follows the dividend's sign; it is not always nonnegative.
+Integer `MIN_I64 % -1` is zero. Like Simple's integer division, integer
+remainder by zero produces zero. Unused arithmetic can be removed.
+
+Floating-point operands use the same truncating-quotient rule: `7.5 % 2.0`
+is `1.5`. A zero divisor or infinite dividend produces NaN; a finite dividend
+modulo infinity is unchanged, and a zero result retains the dividend's sign.
+Mixed integer/float operands convert to floating point, as with `*` and `/`.
+The compound assignment `x %= y` stores `x % y` back into `x`.
+`mod` is an ordinary identifier.
+
+Clock uses `second % 10` for its last digit and `i % 5 == 0` for major
+dial ticks. The time library uses the operator for leap years and calendar
+fields, adding a positive period when it needs a nonnegative result.
+
+[`ModNode`](../../src/main/java/com/seaofnodes/simple/node/ModNode.java) follows
+`DivNode`: two operands, one result, and shared arithmetic folding and type
+checking. It has no control or memory effects. Integer machine encodings handle
+zero divisors and signed overflow to preserve the ideal operations' results
+without hardware faults. Floating remainder uses a memory-preserving runtime
+helper selected as a machine operation; the ideal graph stays ordinary arithmetic.
+`make test CLASS=ModTest` covers folding, evaluation, native execution, imports,
+and code generation for all three targets.
+
+
+## Graphics and sound
+
+Graphics and sound are optional. The Simple language and compiler do not need
+them. The `sys` library includes bindings to the native C backends, but you do
+not need those backends for programs without a display or sound. Their
+dependencies download with the existing `make init` setup command.
+
+Each pixel holds 24 bits of RGB color in a `u32`. A pixel buffer is a `u32[]`.
+
+[`sys.draw.Canvas`](../../src/main/smp/sys/draw/Canvas.smp) draws pixels, rectangles,
+circles, thick lines, and text into a `u32[]` pixel buffer. Shapes clip to the
+canvas. The 3x5 font includes digits, letters, and punctuation such as colons
+and slashes. Its glyphs are stored in a read-only array.
+
+`sys.draw` supplies a few color constants plus `rgb(r,g,b)` to clamp and pack
+computed color components.
+
+`sys.draw.Button` handles button hover, press, release, and disabled states.
+
+`sys.gfx` opens a window, presents pixels, and reads keyboard and mouse input.
+The window backend uses MiniFB. `gfx.wait(timeout_ms)` waits for input or a
+timeout, so animation need not spin continuously.
+
+`sys.audio` plays built-in cues or sample arrays generated in Simple. Its
+optional miniaudio backend plays sound while the game continues. The games
+can run silently when audio is unavailable.
+
+See [drawing](../../src/main/smp/sys/draw/README.md), [windows](../../src/main/smp/sys/gfx.md), and
+[audio](../../src/main/smp/sys/audio.md) for the APIs.
+
+
+## Time library
+
+[`sys.time`](../../src/main/smp/sys/time.smp) provides wall-clock time, monotonic
+time, sleep, calendar conversion, ISO date parsing, and formatting. Use
+wall-clock time for dates. Use monotonic time for elapsed time and deadlines -
+perfect for games.
+
+Instants and durations normally use `i64` milliseconds. Constants show their
+units directly: `SECOND=1000`, `MINUTE=60*SECOND`, and `HOUR=60*MINUTE`.
+
+`sys.time.Timers` supports one-shot and repeating timers. The event loop polls
+for due timer IDs; no timer thread or callback is needed. This might be a mindset
+change for you game writers, it depends on what era you started writing them.
+Here it is all single-threaded and event-loop driven - but when there is nothing
+left to do, you need to wait for an event.
+
+Time also works in string interpolation:
+
+```simple
+sys.io.p("UTC %tT(sys.time.now())\n");
+```
+
+Millisecond parameters and fields end in `_ms` to distinguish them from other
+integers.
+
+See [time and timers](../../src/main/smp/sys/time/README.md) for local-time formatting and other forms.
+
+
+## Array initializers
+
+An array can use a list of values or an expression evaluated for each index:
+
+```simple
+val primes = new int[]{2,3,5,7};
+val squares = new int[10]{int i -> i*i;};
+val names = new u8[~][~2]{"Alice","Bob"};
+```
+
+The generator runs once per element, from index zero through length minus one.
+Its body can contain statements and return the element value. It can read
+surrounding locals but cannot reassign them; it is not a true function.
+
+If the array has a fixed initialization list, then the length can be inferred.
+
+
+`[~n]` (or `[~]` with a list) makes an array read-only. `val` prevents
+reassignment of the array variable, but not changes to its contents. In C,
+this is the classic `const u8* const` distinction: the first `const` protects
+the contents; the second protects the pointer. Array initialization normally
+runs at runtime; read-only does not require compile-time evaluation.
+
+When the compiler knows a read-only integer array's complete contents, it can
+emit them as static ELF data. Identical constant arrays can share storage,
+just like strings. Canvas's font now uses this path instead of allocating
+and filling its table at startup. The trigger is a `TypeConAry` constant type,
+regardless of which node computes it. Constant lists are the first new
+producer; generators still run at runtime.
+
+Initializers also allow arrays of non-null references: every element is
+supplied before the array becomes accessible. In the example, `names` is a
+read-only array of two non-null, read-only strings.
+
+
+## Math support and intrinsics
+
+[`sys.math`](../../src/main/smp/sys/math.smp) provides `PI`, `E`, `min`, `max`, and
+five native math functions, each with signature `{ f64 -> f64 }`:
+
+| Function | Result |
+| --- | --- |
+| `sin(x)` | Sine of an angle in radians |
+| `cos(x)` | Cosine of an angle in radians |
+| `exp(x)` | e raised to x |
+| `log(x)` | Natural logarithm of x |
+| `sqrt(x)` | Nonnegative square root of x |
+
+```simple
+f64 diagonal = sys.math.sqrt(2.0);
+f64 height = sys.math.sin(sys.math.PI/6.0);
+f64 power = sys.math.exp(2.0);
+f64 exponent = sys.math.log(power);
+```
+
+These are direct bindings to the host's libm; the standard linker already
+includes `-lm`. Results and domain/range errors, including `errno`, follow
+that library. See the native references for
+[trigonometry](https://sourceware.org/glibc/manual/2.43/html_node/Trig-Functions.html)
+and [exponents, logarithms, and square roots](https://sourceware.org/glibc/manual/latest/html_node/Exponents-and-Logarithms.html).
+They remain ordinary C calls, so they are not constant-folded or discarded as
+pure intrinsics. Clock uses `sin` and `cos` for its dial and hands.
+`make test CLASS=MathTest` checks native results, special values, indirect calls,
+and code generation for all three targets.
+
+Two representation operations are compiler intrinsics:
+
+```simple
+i64 bits = sys.math.f64Bits(1.0); // 0x3ff0000000000000
+f64 value = sys.math.f64FromBits(bits); // 1.0
+```
+
+They *reinterpret* the same 64 bits, preserving signed zero, infinities,
+subnormals, and NaN signs and payloads, including the signaling bit. They perform
+no arithmetic and have no memory effects. Applying either operation followed
+by the other is an identity. Ordinary assignments between integer and
+floating-point types still perform numeric conversion; floating-point
+arithmetic may change a NaN representation.
+
+These functions introduce compiler intrinsics: ordinary C bindings with reserved
+external symbols, fixed signatures, and known meanings. The compiler recognizes
+the external function's identity, including aliases and imported bindings, and
+can replace its calls with ideal IR nodes. It does not recognize the spelling of
+a local variable or an unrelated Simple function with the same name. No new
+expression syntax is needed.
+
+| External C symbol | Signature | Public alias |
+| --- | --- | --- |
+| `simple_f64_bits` | `{ f64 -> i64 }` | `sys.math.f64Bits` |
+| `simple_f64_from_bits` | `{ i64 -> f64 }` | `sys.math.f64FromBits` |
+
+[`Intrinsic.java`](../../src/main/java/com/seaofnodes/simple/node/Intrinsic.java) owns the
+reserved-symbol table, signatures, effect queries, inlining, and ideal nodes.
+Call/CallEnd delegate to it. The cheap inliner checks intrinsics before requiring
+a Simple body or Return edge. It validates the signature and actual arguments,
+then replaces the complete control/memory/value state. For these pure operations,
+control and memory pass through unchanged.
+
+Unknown indirect targets keep ordinary calls. The runtime's
+[`simple_crt.c`](../../src/main/c/simple_crt.c) supplies C definitions using `memcpy`
+to preserve representations without aliasing tricks. A replacement definition
+must honor the same contract. Ordinary C functions remain opaque to the optimizer.
+
+The ideal nodes support constant folding, inverse cancellation, evaluation, and
+serialization. Floating-point constant interning and serialization retain raw
+NaN bits. x86 emits `MOVQ` between XMM and integer registers; ARM emits `FMOV`,
+and RISC-V emits `FMV.X.D` / `FMV.D.X`. Register allocation may add copies or
+spills, and normal module-initialization checks still apply.
+
+Future intrinsics such as compare-and-swap or fences must define their memory
+and escape effects explicitly, using nodes with the required ordering
+dependencies. They must not inherit the pure conversions' passthrough memory
+behavior. Atomic operations and hardware square root are not introduced here.
+
+`make test CLASS=IntrinsicTest` checks representation preservation, folding,
+type errors, side effects, indirect C fallback, binary imports, and instruction
+selection on all three backends, including emulation and native x86 execution.
+
+Simple also now recognizes hexadecimal (`0xff0000`) and leading-zero octal
+(`025755`) integer literals.
+
+
+## Compiler fixes
+
+- Syntax errors raised through JUnit now show the source line and error pointer.
+ Actual compiler failures still report Java stack traces.
+- Integer memory operations on x86 use the correct register class. This fixes
+ the instruction-encoding failure exposed by Dijkstra.
+- Floating-point comparisons handle NaNs correctly in branches and Boolean
+ results. Floating-point negation also handles signed zero correctly.
+- Array-initializer memory tracking no longer adds an unrelated function to
+ the returned result. Loop-load optimization checks that the pointer is
+ available before moving a load.
+- Imported read-only primitive arrays retain their types. Object files can
+ represent more than 255 distinct memory regions.
+- Floating-point constants and register copies preserve raw NaN bits.
+
+## Further reading
+
+The [grammar and code map](31-grammar.md) is this chapter's language
+reference. Runnable programs and their controls are in the
+[examples](examples/README.md). Library API references live beside their
+implementations: [drawing](../../src/main/smp/sys/draw/README.md),
+[windows](../../src/main/smp/sys/gfx.md), [audio](../../src/main/smp/sys/audio.md), and
+[time](../../src/main/smp/sys/time/README.md).
+
+For inherited compiler behavior, start with [escape analysis in Chapter 27](../chapter27/README.md)
+and [construction and partial references in Chapter 29](../chapter29/README.md).
+Chapter 29 also links the detailed construction and escape implementation notes.
+
+## Build and run
+
+From the `chapter31` directory:
+
+```sh
+make libs # Download dependencies once.
+make run-graphical-tictactoe
+make run-clock
+make run-breakout
+```
+
+Dependencies stay cached across `make clean`. The run targets build the needed
+window and audio backends. Use `graphical-tictactoe`, `clock-example`, or
+`breakout` to build an executable without opening a window.
+
+Run the ordinary tests without a display or audio device:
+
+```sh
+make tests_nographics
+```
diff --git a/docs/chapter31/examples/A_helloWorld.smp b/docs/chapter31/examples/A_helloWorld.smp
new file mode 100644
index 00000000..4ed6abdf
--- /dev/null
+++ b/docs/chapter31/examples/A_helloWorld.smp
@@ -0,0 +1,2 @@
+sys.io.p("Hello, World!\n");
+return 0;
diff --git a/docs/chapter31/examples/Breakout.smp b/docs/chapter31/examples/Breakout.smp
new file mode 100644
index 00000000..d60894ac
--- /dev/null
+++ b/docs/chapter31/examples/Breakout.smp
@@ -0,0 +1,369 @@
+// Clear 24 x 8 bricks. Arrows or mouse move; Space/click serves; P pauses;
+// R restarts; Q/Escape exits. Any argument runs ten frames as a smoke test.
+u32 WIDTH = 1008, HEIGHT = 760, COLS = 24, ROWS = 8;
+int LEFT = 24, RIGHT = 984, TOP = 84, BOTTOM = 718;
+int BRICK_TOP = 152, BRICK_DX = 40, BRICK_DY = 22, BRICK_W = 36, BRICK_H = 18;
+int RADIUS = 5, PADDLE_HALF = 56, PADDLE_Y = 674;
+int READY = 0, PLAY = 1, WON = 2, LOST = 3;
+int KEY_LEFT = 263, KEY_RIGHT = 262; // MiniFB key codes; gfx.LEFT is a mouse button.
+i64 STEP_ms = 8, FRAME_ms = 16;
+u32 BACKGROUND = 0x0b1220, WHITE = 0xeef7ff, MUTED = 0x8aabc4, CYAN = 0x4ce0ef;
+val COLORS = new u32[~]{0xff5268,0xff8050,0xffb548,0xffdb58,
+ 0x9bdd58,0x45d8b0,0x49b9f5,0x8d94ff};
+val DIGITS = new u8[~][~]{"0","1","2","3","4","5","6","7","8","9"};
+
+struct Game {
+ u8[] bricks = new u8[COLS*ROWS]{int i -> 1;};
+ int score = 0, remaining = COLS*ROWS, lives = 3, depth = 1, phase = READY;
+ bool boosted = false, backWall = false, paused = false;
+ f64 x = 504.0, y = 663.0, dx = 0.4, dy = -0.916515138991168;
+
+ // Fixed 8 ms simulation, split further to travel at most two pixels per step.
+ // Even at maximum boosted speed a ball cannot tunnel through an 18 px brick.
+ val _tick = { int direction ->
+ if( paused || phase == WON || phase == LOST ) return 0;
+ _paddle(paddle+direction*6.4);
+ if( phase == READY ) { x = paddle; y = PADDLE_Y-RADIUS-6; return 0; }
+ f64 seconds = 0.008; // 8ms
+ while( seconds > 0.000000001 && phase == PLAY ) {
+ f64 dt = 2.0/speed;
+ if( dt > seconds ) dt = seconds;
+ seconds -= dt;
+ f64 oldX = x, oldY = y;
+ x += dx*speed*dt;
+ y += dy*speed*dt;
+ if( x < LEFT+RADIUS && dx < 0.0 ) {
+ x = 2.0*(LEFT+RADIUS)-x; dx = -dx; _cue(1);
+ }
+ if( x > RIGHT-RADIUS && dx > 0.0 ) {
+ x = 2.0*(RIGHT-RADIUS)-x; dx = -dx; _cue(1);
+ }
+ if( y < TOP+RADIUS && dy < 0.0 ) {
+ y = 2.0*(TOP+RADIUS)-y; dy = -dy;
+ backWall = true; _cue(1);
+ }
+ if( dy > 0.0 && oldY <= PADDLE_Y-RADIUS && y >= PADDLE_Y-RADIUS &&
+ paddle-PADDLE_HALF-RADIUS <= x <= paddle+PADDLE_HALF+RADIUS ) _rebound();
+ if( y > BOTTOM+RADIUS ) {
+ _lostBall();
+ break;
+ }
+ // Map the center into the grid of radius-expanded brick boxes.
+ // Their overlap is smaller than one cell: at most 2 x 2 candidates.
+ if( x <= LEFT+2 -RADIUS || x >= LEFT+2 +(COLS-1)*BRICK_DX+BRICK_W+RADIUS ||
+ y <= BRICK_TOP-RADIUS || y >= BRICK_TOP+(ROWS-1)*BRICK_DY+BRICK_H+RADIUS )
+ continue;
+ int col = (x-(LEFT+2 -RADIUS))/BRICK_DX;
+ int row = (y-(BRICK_TOP-RADIUS))/BRICK_DY;
+ bool hit = false;
+ for( int r = row > 0 ? row-1 : 0; r <= row && r < ROWS && !hit; r++ )
+ for( int c = col > 0 ? col-1 : 0; c <= col && c < COLS; c++ ) {
+ int i = r*COLS+c;
+ if( bricks[i] == 0 ) continue;
+ f64 left = LEFT+2 +c*BRICK_DX-RADIUS;
+ f64 top = BRICK_TOP+r*BRICK_DY-RADIUS;
+ f64 right = left+BRICK_W+2*RADIUS;
+ f64 bottom= top +BRICK_H+2*RADIUS;
+ if( left < x < right && top < y < bottom ) {
+ bool back = false;
+ // Resolve the face crossed this step, using the previous center.
+ // Vertical faces win a simultaneous corner contact.
+ if( oldY <= top && dy > 0.0 ) {
+ y = top; dy = -dy; back = true;
+ } else if( oldY >= bottom && dy < 0.0 ) {
+ y = bottom; dy = -dy;
+ } else if( oldX <= left && dx > 0.0 ) {
+ x = left; dx = -dx;
+ } else if( oldX >= right && dx < 0.0 ) {
+ x = right; dx = -dx;
+ } else continue; // Missed all bricks
+ _brick(i,back);
+ hit = true;
+ break;
+ }
+ }
+ }
+ return 0;
+ };
+
+
+ // Several sound things might happen in this event, pick one
+ int sound = 0; // Increasing priority: wall, paddle, brick, boost, miss, win.
+ val _cue = { int snd -> if( snd > sound ) sound = snd; };
+
+ // Ball speed is a fraction of deepest brick hit, plus backwall boost
+ f64 speed;
+ val _speed = { -> speed = (320.0+35.0*(depth-1))*(boosted ? 1.65 : 1.0); };
+
+ // Clamp paddle to wall sides
+ f64 paddle;
+ val _paddle = { f64 x ->
+ paddle = x < LEFT +PADDLE_HALF ? LEFT +PADDLE_HALF :
+ x > RIGHT-PADDLE_HALF ? RIGHT-PADDLE_HALF :
+ x;
+ };
+
+ // Hit the paddle
+ val _rebound = { ->
+ // Where along the paddle did you hit?
+ f64 offset = (x-paddle)/PADDLE_HALF;
+ if( offset < -1.0 ) offset = -1.0;
+ if( offset > 1.0 ) offset = 1.0;
+ dx = 0.88*offset;
+ // A near-center hit still drifts sideways instead of repeating forever.
+ if( -0.12 < dx < 0.12 ) dx = dx < 0.0 ? -0.12 : 0.12;
+ dy = -_sqrt(1.0-dx*dx); // Bounce upwards speed
+ y = PADDLE_Y-RADIUS; // Reset ball hit to top of paddle
+ backWall = false; // Did not hit back wall
+ _cue(2); // Paddle bounce sound
+ };
+
+ // Hit a brick?
+ int soundDepth; // Which brick depth for the boop
+ val _brick = { int index, bool back ->
+ if( bricks[index] == 0 ) return 0; // No brick to hit!
+ bricks[index] = 0; // Clear brick
+ int row = ROWS-index/COLS; // Get brick row
+ score += row; // Score by row
+ remaining--; // Fewer bricks to iwn
+ if( row > depth ) depth = row; // Max depth seen
+ // Brick-hit sound
+ if( sound <= 3 ) { _cue(3); soundDepth = row; }
+ if( back && backWall && !boosted ) { _cue(3); boosted = true; }
+ if( remaining == 0 ) { _cue(6); phase = WON; }
+ _speed();
+ return 0;
+ };
+
+ // Missed ball with paddle
+ val _lostBall = { ->
+ lives--;
+ phase = lives == 0 ? LOST : READY;
+ backWall = false;
+ depth = 1;
+ boosted = false;
+ _speed();
+ x = paddle; y = PADDLE_Y-RADIUS-6;
+ _cue(5);
+ };
+
+ // Reset for another round
+ val _reset = { ->
+ for( int i = 0; i < bricks#; i++ ) bricks[i] = 1;
+ score = 0;
+ remaining = COLS*ROWS;
+ lives = 3;
+ depth = 1;
+ phase = READY;
+ boosted = false;
+ backWall = false;
+ paused = false;
+ sound = 0;
+ soundDepth = 1;
+ paddle = 504.0;
+ x = paddle;
+ y = PADDLE_Y-RADIUS-6;
+ _speed();
+ };
+
+ // --------------------------------
+ // Drawing code
+ val _hud = { !sys.draw.Canvas c ->
+ c.text(24,22,"BREAKOUT",5,WHITE);
+ c.text(264,20,"SCORE",2,MUTED);
+ _number(c,264,40,score,3,4,WHITE);
+ c.text(424,20,"BRICKS",2,MUTED);
+ _number(c,424,40,remaining,3,4,WHITE);
+ c.text(584,20,"BALLS",2,MUTED);
+ for( int i = 0; i < lives; i++ ) c.fillCircle(590+23*i,50,5,CYAN);
+ c.text(714,20,"SPEED",2,MUTED);
+ int ispeed = speed;
+ _number(c,714,40,ispeed,3,4,boosted ? COLORS[0] : WHITE);
+ c.text(838,40,boosted ? "BOOST!" : "NORMAL",3,boosted ? COLORS[0] : MUTED);
+ };
+
+
+ val _bricks = { !sys.draw.Canvas c ->
+ c.fillRect(LEFT-4,TOP-4,RIGHT-LEFT+8,4,MUTED);
+ c.fillRect(LEFT-4,TOP,4,BOTTOM-TOP,0x29435a);
+ c.fillRect(RIGHT,TOP,4,BOTTOM-TOP,0x29435a);
+ c.text(376,108,boosted ? "BACK WALL BOOST ACTIVE" : "BREAK THROUGH FOR A BOOST",2,boosted ? COLORS[0] : MUTED);
+ for( int i = 0; i < bricks#; i++ ) {
+ if( bricks[i] == 0 ) continue;
+ int row = i/COLS;
+ i64 x = LEFT+2+(i%COLS)*BRICK_DX, y = BRICK_TOP+row*BRICK_DY;
+ c.fillRect(x,y,BRICK_W,BRICK_H,COLORS[row]);
+ c.fillRect(x,y,BRICK_W,2,WHITE);
+ }
+ };
+
+ val _overlay = { !sys.draw.Canvas c ->
+ if( phase != PLAY || paused ) {
+ c.fillRect(246,422,516,108,0x17263a).rect(246,422,516,108,2,0x29435a);
+ u8[~] title = paused ? "PAUSED" : phase == WON ? "WALL CLEARED!" : phase == LOST ? "GAME OVER" : "READY?";
+ c.text(504-(title#*4-1)*4/2,442,title,4,WHITE);
+ u8[~] help = paused ? "P TO CONTINUE" : phase == WON || phase == LOST ? "R TO PLAY AGAIN" : "SPACE OR CLICK TO SERVE";
+ c.text(504-(help#*4-1)*2/2,490,help,2,CYAN);
+ }
+ return 0;
+ };
+
+ // With this Canvas, we draw into the blank canvas, then "present". The
+ // underlying graphics lib copies the bits, and we are then free to clear
+ // and draw again while the old bits continue to be presented.
+ val _draw = { !sys.draw.Canvas c ->
+ c.clear(BACKGROUND);
+ _hud(c);
+ _bricks(c);
+ i64 paddle = paddle, ballX = x, ballY = y;
+ int glowRadius = RADIUS+3;
+ c.fillRect(paddle-PADDLE_HALF,PADDLE_Y,2*PADDLE_HALF,12,CYAN);
+ c.fillRect(paddle-PADDLE_HALF+4,PADDLE_Y+2,2*PADDLE_HALF-8,2,WHITE);
+ c.fillCircle(ballX,ballY,glowRadius,boosted ? 0x672a42 : 0x224b61);
+ c.fillCircle(ballX,ballY,RADIUS,boosted ? COLORS[0] : WHITE);
+ _overlay(c);
+ c.text(24,738,"ARROWS / MOUSE: MOVE SPACE / CLICK: SERVE P: PAUSE R: RESTART Q / ESC: QUIT",2,MUTED);
+ };
+
+ // Served and still holding serve key
+ bool serveHeld;
+ // Paused and still holding pause key
+ bool pauseHeld;
+ // Restart and still holding restart key
+ bool restartHeld;
+ // Last mouse position; track moving mouse
+ int lastMouse;
+
+ // Read and act on the controls
+ val _input = { sys.draw.Canvas c ->
+ val gfx = sys.gfx;
+ bool serve = gfx.key(' ') || gfx.button(gfx.LEFT);
+ bool pause = gfx.key('P');
+ bool restart= gfx.key('R');
+
+ // Keyboard direction and mouse position
+ int direction = (gfx.key(KEY_RIGHT) ? 1 : 0)-(gfx.key(KEY_LEFT) ? 1 : 0);
+ int mouse = c.localX(gfx.mouseX());
+
+ // Restart requested
+ restartHeld = debounce( restart, restartHeld, { -> _reset(); sys.audio.stop(); } );
+
+ // Playing or ready to play game?
+ if( phase == READY || phase == PLAY ) {
+ // Flip pause state
+ pauseHeld = debounce( pause, pauseHeld, { -> paused = !paused; } );
+
+ // If no key and mouse moved, set paddle to mouse
+ if( mouse >= 0 && mouse != lastMouse && direction == 0 && !paused ) {
+ _paddle(mouse*1.0); // Set paddle to mouse
+ // If READY and not PLAY, ball tracks paddle directly
+ if( phase == READY ) x = paddle;
+ }
+ lastMouse = mouse;
+
+ }
+
+ // Serve requested
+ serveHeld = debounce( serve, serveHeld, _serve );
+
+ // Return key direction, so the tick tracking can slide paddle smoothly
+ return direction;
+ };
+
+ val debounce = { bool b, bool bHeld, { int } action ->
+ if( b && !bHeld ) // Action requested and repeating
+ action(); // Do action
+ b; // Dont action again, until 'b' is released
+ };
+
+
+ // Serve the ball; give it a nominal direction and speed
+ val _serve = { ->
+ if( phase == READY && !paused ) {
+ phase = PLAY;
+ dx = 0.4;
+ dy = -_sqrt(1.0-dx*dx);
+ }
+ return 0;
+ };
+};
+
+// Fixed-width decimal labels avoid allocating new strings on every frame.
+val _number = { !sys.draw.Canvas c, i64 x, i64 y, int value, int digits, int scale, u32 color ->
+ for( int i = 0; i < digits; i++ ) {
+ c.text(x+(digits-1-i)*4*scale,y,DIGITS[value%10],scale,color);
+ value /= 10;
+ }
+};
+
+// Short, fading triangle waves; the array initializer builds PCM once at startup.
+val _tone = { int period ->
+ val samples = new i16[~2400]{int i ->
+ int phase = i%period;
+ int triangle = phase < period/2 ? phase : period-phase;
+ return (triangle*4-period)*6000/period*(2400-i)/2400;
+ };
+ int handle = sys.audio.load(samples);
+ return handle < 0 ? sys.audio.BOOP : handle;
+};
+
+
+// Fast low accuracy sqrt
+val _sqrt = { f64 n ->
+ f64 r = 1.0;
+ for( int i = 0; i < 8; i++ ) r = (r+n/r)*0.5;
+ return r;
+};
+
+val main = { u8[~][] args ->
+ // Shortcuts
+ val gfx = sys.gfx, audio = sys.audio;
+
+ // Open a window
+ if( gfx.open("Simple Breakout",WIDTH,HEIGHT) != gfx.OK ) return 1;
+
+ // Audio setup; pre-specify a series of sounds
+ audio.open(); // Optional: a missing audio backend leaves play silent.
+ val sounds = new int[~]{0,_tone(120),_tone(80),audio.BOOP,audio.WIN,audio.LOSE,audio.WIN};
+ // Bottom to top: roughly 333..800 Hz, below the old 1000 Hz brick tone.
+ val brickSounds = new int[~ROWS]{int i -> int period = 144-i*12; _tone(period);};
+
+ // Setup drawing board
+ val c = new sys.draw.Canvas(WIDTH,HEIGHT);
+
+ // Setup game contents
+ val g = new Game;
+ g._reset();
+
+ //
+ int frames = 0, status = gfx.OK;
+ i64 last_ms = sys.time.monotonic(), pending_ms = 0, frame_ms = last_ms;
+
+ while( status == gfx.OK ) {
+ if( gfx.key('Q') || gfx.key(gfx.ESCAPE) ) break;
+ // Physics stays in base coordinates; only drawing and input scale.
+ if( c.resize(gfx.width(),gfx.height()) ) {
+ g.lastMouse = c.localX(gfx.mouseX());
+ frame_ms = 0;
+ }
+ int direction = g._input(c);
+ i64 now_ms = sys.time.monotonic(), elapsed_ms = now_ms-last_ms;
+ last_ms = now_ms;
+ // Drop long stalls instead of teleporting the ball after a window drag.
+ pending_ms += elapsed_ms < 0 ? 0 : elapsed_ms > 64 ? 64 : elapsed_ms;
+ while( pending_ms >= STEP_ms ) { g._tick(direction); pending_ms -= STEP_ms; }
+ if( g.sound != 0 ) {
+ audio.play(g.sound == 3 ? brickSounds[g.soundDepth-1] : sounds[g.sound]);
+ g.sound = 0;
+ }
+ if( now_ms >= frame_ms ) {
+ g._draw(c);
+ status = gfx.presentSize(c.pixels,c.width,c.height);
+ frame_ms = now_ms+FRAME_ms;
+ if( args# > 1 && ++frames == 10 ) break;
+ }
+ if( status == gfx.OK ) status = gfx.wait(STEP_ms-pending_ms);
+ }
+ audio.close(); gfx.close();
+ return status == gfx.ERROR ? 1 : 0;
+};
diff --git a/docs/chapter31/examples/BubbleSort.smp b/docs/chapter31/examples/BubbleSort.smp
new file mode 100644
index 00000000..6bdb13a9
--- /dev/null
+++ b/docs/chapter31/examples/BubbleSort.smp
@@ -0,0 +1,38 @@
+
+// An implementation of
+// https://sampleprograms.io/projects/bubble-sort/
+//
+// Bubble sort, with reading (parsing) and writing (formatting) the data.
+
+val sort = { !sys.aryi64 nums ->
+ sys.aryi64?! more = nums;
+ while( more ) {
+ more = null;
+ for( u32 i = 0; i < nums.len-1; i++ )
+ if( nums.buf[i] > nums.buf[i+1] ) {
+ u32 next = i+1;
+ more = nums.swap(i,next);
+ }
+ }
+};
+
+// Read one process argument of the form "[ 4, 3, 2, 1]" and print it sorted.
+// args[0] is the executable name, as with native C argc/argv.
+val main = { u8[~][] args ->
+ val usage = { ->
+ sys.io.p("Usage: please provide a list of at least two integers to sort in the format \"[1, 2, 3, 4, 5]\"\n");
+ return 0;
+ };
+ if( args# != 2 ) return usage();
+
+ var nums = sys.aryi64.parseAryI64(args[1]);
+ if( !nums ) return usage();
+ if( nums.len < 2 ) return usage();
+
+ // Bubble sort array of integers
+ sort(nums);
+
+ // Print the same bracketed array-list format accepted as input.
+ nums.str().add('\n').write(1);
+ return 0;
+};
diff --git a/docs/chapter31/examples/Capitalize.smp b/docs/chapter31/examples/Capitalize.smp
new file mode 100644
index 00000000..00fdd481
--- /dev/null
+++ b/docs/chapter31/examples/Capitalize.smp
@@ -0,0 +1,23 @@
+
+// An implementation of
+// https://sampleprograms.io/projects/capitalize/
+
+val main = { u8[~][] args ->
+ if( args# > 2 ) {
+ sys.io.p("Use quotes around multiple strings.\n");
+ return 0;
+ }
+ if( args# != 2 || args[1]# == 0 ) {
+ sys.io.p("Usage: please provide a string\n");
+ return 0;
+ }
+
+ u8[~] input = args[1];
+ var output = new u8[input# + 1];
+ u32 len = input#;
+ sys.ary.copy(output,0,input,0,len);
+ output[0] = sys.char.toupper(input[0]);
+ output[input#] = '\n';
+ sys.io.p(output);
+ return 0;
+};
diff --git a/docs/chapter31/examples/Clock.smp b/docs/chapter31/examples/Clock.smp
new file mode 100644
index 00000000..fb50f84e
--- /dev/null
+++ b/docs/chapter31/examples/Clock.smp
@@ -0,0 +1,128 @@
+// Local clocks; click the button or press Space to switch. Q/Escape exits.
+// Any argument runs ten frames, exercising both faces for smoke tests.
+u32 GREEN = 0x62ff70, DIM = 0x123d20, BACKGROUND = 0x020b05;
+
+val main = { u8[~][] args ->
+ val gfx = sys.gfx;
+ val time = sys.time;
+ // The main Canvas
+ val screen = new sys.draw.Canvas(720,540);
+ if( gfx.open("Simple digital and analog clocks",screen.width,screen.height) != gfx.OK ) return 1;
+
+ // Button to flip clock style
+ val button = new sys.draw.Button(220,454,280,52,"ANALOG CLOCK");
+ val timers = new sys.time.Timers();
+ u32 frame_id = timers.every(33);
+ if( frame_id == 0 ) { gfx.close(); return 1; }
+
+ bool analog = false, held = false;
+ int frames = 0, status = gfx.OK;
+
+ // Main event loop
+ while( status == gfx.OK ) {
+ bool resized = screen.resize(gfx.width(),gfx.height());
+ // Did the user press space bar?
+ bool space = gfx.key(' ');
+ // Did the left mouse button go down?
+ bool down = gfx.button(gfx.LEFT);
+ // ANd did it go down over this button?
+ bool click = button.update(screen.localX(gfx.mouseX()),screen.localY(gfx.mouseY()),down);
+ // If clicked, flip the clock mode
+ if( click || (space && !held) ) analog = !analog;
+ held = space;
+ if( gfx.key('Q') ) break;
+ // Change button label
+ button.label = analog ? "DIGITAL CLOCK" : "ANALOG CLOCK";
+ // If the next timer event is the every-33-msec event
+ if( timers.poll(time.monotonic()) == frame_id || resized ) {
+ // Draw the clock screen and button
+ _draw(screen,time.now(),analog);
+ button.draw(screen,3,GREEN,BACKGROUND,DIM);
+ // Presne the canvas on screen
+ status = gfx.presentSize(screen.pixels,screen.width,screen.height);
+ // Testing only: show 5 frames, flip to analog, show 5 more and exit
+ if( args# > 1 ) {
+ frames++;
+ if( frames == 5 ) analog = true;
+ if( frames == 10 ) break;
+ }
+ }
+ if( status != gfx.OK ) break;
+ // Stall until next timer event
+ status = gfx.wait(time.remaining(timers.nextDeadline(),time.monotonic()));
+ }
+ gfx.close();
+ return status == gfx.ERROR ? 1 : 0;
+};
+
+val _draw = { !sys.draw.Canvas screen, i64 wall_ms, i64 analog ->
+ val d = sys.time.local(wall_ms);
+ screen.clear(BACKGROUND);
+ screen.text(266,24,"SIMPLE CLOCK",4,GREEN);
+ if( analog ) _analog(screen,d.hour,d.minute,d.second,d.millisecond);
+ else _digital(screen,d.hour,d.minute,d.second);
+ screen.text(298,412,"%(sys.time.formatLocal(wall_ms,sys.time.DATE))",4,GREEN);
+ screen.text(249,520,"SPACE SWITCH Q OR ESC QUIT",2,GREEN);
+};
+
+// a..g bits: top, upper-right, lower-right, bottom, lower-left, upper-left,
+// middle. Faint unlit bars retain the old LED figure-eight silhouette.
+val _digitFont = new u8[~]{
+ // 0 1 2 3 4 5 6 7 8 9
+ 0x3f, 0x06, 0x5b, 0x4f, 0x66, 0x6d, 0x7d, 0x07, 0x7f, 0x6f
+};
+val _digitBars = new u8[~]{
+ // x0 y0 x1 y1
+ 14, 0, 58, 0, // a: top
+ 68, 12, 68, 60, // b: upper-right
+ 68, 84, 68, 132, // c: lower-right
+ 14, 144, 58, 144, // d: bottom
+ 4, 84, 4, 132, // e: lower-left
+ 4, 12, 4, 60, // f: upper-left
+ 14, 72, 58, 72 // g: middle
+};
+val _digit = { !sys.draw.Canvas c, int x, int y, i64 digit ->
+ int bits = 0 <= digit < _digitFont# ? _digitFont[digit] : 0;
+ for( int i = 0; i < 7; i++ ) {
+ u32 color = (bits&(1<<i)) != 0 ? GREEN : DIM;
+ int bar = i*4;
+ c.line(x+_digitBars[bar ],y+_digitBars[bar+1],
+ x+_digitBars[bar+2],y+_digitBars[bar+3],10,color);
+ }
+};
+
+val _digital = { !sys.draw.Canvas c, int hour, int minute, int second ->
+ _digit(c, 68,166, hour/10); _digit(c,154,166, hour%10);
+ _digit(c,284,166,minute/10); _digit(c,370,166,minute%10);
+ _digit(c,500,166,second/10); _digit(c,586,166,second%10);
+ for( int i = 0; i < 2; i++ ) {
+ c.fillCircle(254+i*216,214,6,GREEN);
+ c.fillCircle(254+i*216,262,6,GREEN);
+ }
+ c.text(272,352,"LOCAL TIME 24H",3,GREEN);
+};
+val _hand = { !sys.draw.Canvas c, f64 turn, int length, int thickness, u32 color ->
+ f64 angle = turn*2*sys.math.PI;
+ int x = 360+sys.math.sin(angle)*length, y = 232-sys.math.cos(angle)*length;
+ c.line(360,232,x,y,thickness,color);
+};
+val _analog = { !sys.draw.Canvas c, int hour, int minute, int second, int millisecond ->
+ c.circle(360,232,154,3,GREEN);
+ for( int i = 0; i < 60; i++ ) {
+ f64 angle = i/60.0*2*sys.math.PI;
+ bool major = i%5 == 0;
+ int inner = major ? 133 : 143;
+ f64 sine = sys.math.sin(angle), cosine = sys.math.cos(angle);
+ int x0 = 360+sine*inner, y0 = 232-cosine*inner;
+ int x1 = 360+sine* 149 , y1 = 232-cosine* 149 ;
+ c.line(x0,y0,x1,y1,major ? 3 : 1,GREEN);
+ }
+ c.text(349,100,"12",2,GREEN); c.text(484,227,"3",2,GREEN);
+ c.text(357,354, "6",2,GREEN); c.text(230,227,"9",2,GREEN);
+ f64 seconds = second+millisecond/1000.0;
+ f64 minutes = minute+seconds/60.0;
+ _hand(c,(hour%12+minutes/60.0)/12.0,78,8,GREEN);
+ _hand(c,minutes/60.0,112,5,GREEN);
+ _hand(c,seconds/60.0,128,2,0xc3ffcb);
+ c.fillCircle(360,232,6,GREEN);
+};
diff --git a/docs/chapter31/examples/Dijkstra.smp b/docs/chapter31/examples/Dijkstra.smp
new file mode 100644
index 00000000..6591b310
--- /dev/null
+++ b/docs/chapter31/examples/Dijkstra.smp
@@ -0,0 +1,71 @@
+
+// An implementation of
+// https://sampleprograms.io/projects/dijkstra/
+
+val shortestPath = { !sys.aryi64 matrix, int nodes, int src, int dst ->
+ i64 infinity = sys.integer.MAX_I64;
+ var visited = new sys.adt.bitset();
+ // All nodes are infinitely far from each other, except the starting point
+ var dist = new i64[nodes]{ int i -> i == src ? 0 : infinity; };
+
+ i64 result = -1;
+ int count = 0;
+ while( count < nodes && result < 0 ) {
+ int nearest = -1;
+ i64 best = infinity;
+ for( int node = 0; node < nodes; node++ )
+ if( !visited.get(node) && dist[node] < best ) {
+ nearest = node;
+ best = dist[node];
+ }
+ if( nearest < 0 ) count = nodes;
+ else {
+ if( nearest == dst ) return best;
+ visited.set(nearest);
+ for( int node = 0; node < nodes; node++ ) {
+ u32 index = nearest*nodes + node;
+ i64 weight = matrix.get(index);
+ if( weight > 0 && !visited.get(node) && best+weight < dist[node] )
+ dist[node] = best+weight;
+ }
+ }
+ count++;
+ }
+ return result;
+};
+
+val usage = { ->
+ sys.io.p("Usage: please provide three inputs: a serialized matrix, a source node and a destination node\n");
+ return 0;
+};
+
+val main = { u8[~][] args ->
+ // Exactly 3 args
+ if( args# != 4 ) return usage();
+ // First is a serialized square matrix of positive numbers
+ var matrix = sys.aryi64.parseAryI64(args[1]);
+ if( !matrix ) return usage();
+ if( !matrix.len ) return usage();
+ // All numbers are positive
+ for( u32 i = 0; i < matrix.len; i++ )
+ if( matrix.get(i) < 0 ) return usage();
+ // Matrix is square
+ int nodes = 0;
+ while( nodes*nodes < matrix.len ) nodes++;
+ if( nodes*nodes != matrix.len )
+ return usage(); // Not a square matrix
+
+ // src,dst are values within the matrix
+ i64 src = sys.aryu8.atoi(args[2]);
+ i64 dst = sys.aryu8.atoi(args[3]);
+ if( src < 0 || src >= nodes || dst < 0 || dst >= nodes )
+ return usage(); // Source and destination land within the graph
+
+ int source = src, destination = dst;
+ i64 cost = shortestPath(matrix,nodes,source,destination);
+ if( cost >= 0 ) {
+ new sys.aryu8().num(cost).add('\n').write(1);
+ return 0;
+ }
+ return usage();
+};
diff --git a/docs/chapter31/examples/FileIO.smp b/docs/chapter31/examples/FileIO.smp
new file mode 100644
index 00000000..59b3159e
--- /dev/null
+++ b/docs/chapter31/examples/FileIO.smp
@@ -0,0 +1,52 @@
+
+// An implementation of
+// https://sampleprograms.io/projects/file-input-output/
+
+val FILE = "output.txt";
+
+val main = { u8[~][] args ->
+ var str = new sys.aryu8();
+ str.addAry("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n");
+ str.addAry("Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n");
+ str.addAry("Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.\n");
+ str.addAry("Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n");
+
+ // Create
+ i32 fd = sys.io.create(FILE);
+ if( fd == -1 ) return _error();
+ // Write
+ u32 len = str.len;
+ int wrote = sys.io.writeOff(fd,str.buf,0,len);
+ if( wrote == -1 ) return _error();
+ if( wrote != str.len ) return _error2(-2);
+ // Close
+ if( sys.io.close(fd) != 0 ) return _error();
+
+ // Open
+ i32 fd2 = sys.io.open(FILE);
+ if( fd2 == -1 ) return _error();
+ // Read
+ var got = sys.io.read(fd2);
+ if( !got ) return _error();
+ if( got# != str.len ) return _error2(-3);
+ // Close
+ if( sys.io.close(fd2) != 0 ) return _error();
+
+ // Check contents are equal
+ if( sys.ary.cmp(got,0,str.buf,0,len) )
+ return _error2(-4);
+
+ // Remove
+ if( sys.io.remove(FILE) != 0 ) return _error();
+
+ sys.io.p("File I/O succeeded\n");
+ return 0;
+};
+
+val _error2 = { i32 errno ->
+ sys.io.remove(FILE);
+ new sys.aryu8().addAry("Failed with error code ").num(errno).add('\n').write(sys.libc.STDERR);
+ sys.libc._exit(errno);
+};
+
+val _error = { -> _error2(sys.libc.errno()); };
diff --git a/docs/chapter31/examples/Graphics.smp b/docs/chapter31/examples/Graphics.smp
new file mode 100644
index 00000000..1878e97d
--- /dev/null
+++ b/docs/chapter31/examples/Graphics.smp
@@ -0,0 +1,26 @@
+// Optional graphics smoke test: pixels are drawn entirely in Simple.
+// Pass any argument for a short, self-closing test; otherwise close or press Esc.
+val main = { u8[~][] args ->
+ if( sys.gfx.open("Simple pixels",320,240) != sys.gfx.OK ) return 1;
+ val c = new sys.draw.Canvas(320,240);
+ int result = sys.gfx.OK;
+ bool dirty = true;
+ int frames = 0;
+ while( result == sys.gfx.OK ) {
+ if( c.resize(sys.gfx.width(),sys.gfx.height()) ) dirty = true;
+ if( dirty ) {
+ // The gradient fills the window, including non-4:3 shapes.
+ int dx = c.width > 1 ? c.width-1 : 1, dy = c.height > 1 ? c.height-1 : 1;
+ for( int y = 0; y < c.height; y++ )
+ for( int x = 0; x < c.width; x++ )
+ c.pixels[y*c.width+x] = (x*255/dx << 16) | (y*255/dy << 8) | 64;
+ result = sys.gfx.presentSize(c.pixels,c.width,c.height);
+ if( result != sys.gfx.OK ) break;
+ dirty = false;
+ }
+ result = sys.gfx.poll(true);
+ if( args# > 1 && ++frames == 5 ) break;
+ }
+ sys.gfx.close();
+ return result == sys.gfx.ERROR ? 1 : 0;
+};
diff --git a/docs/chapter31/examples/README.md b/docs/chapter31/examples/README.md
new file mode 100644
index 00000000..05dcf6cb
--- /dev/null
+++ b/docs/chapter31/examples/README.md
@@ -0,0 +1,119 @@
+# Runnable examples
+
+These programs live beside the documentation so readers can find and run them.
+Their non-graphical native regression tests run as part of `make tests`.
+All four graphical demos support window resizing. Clock, Tic-tac-toe, and
+Breakout scale their base layouts uniformly and center them in the window;
+mouse input follows the same transform. Breakout keeps its physics in base
+coordinates, so resizing preserves the current game and ball speed. The pixel
+gradient fills the entire window at its new resolution.
+The optional [pixel-window example](Graphics.smp) uses MiniFB; see
+[graphics setup](../../src/main/smp/sys/gfx.md). `make run-graphics` opens it explicitly.
+The [graphical tic-tac-toe](TicTacToeGraphical.smp) uses the Simple
+[drawing library](../../src/main/smp/sys/draw/README.md). Run it with
+`make run-graphical-tictactoe`; click a cell or press 1–9, R/Space to
+replay, and Q/Escape to quit. The terminal game below remains available.
+Optional [background audio](../../src/main/smp/sys/audio.md) supplies soft move and win/loss cues.
+
+The [digital and analog clock](Clock.smp) demonstrates the [time library](../../src/main/smp/sys/time/README.md),
+green seven-segment digits, smooth clock hands, and a reusable software button.
+Run `make run-clock`; click the button or press Space to switch faces,
+and Q/Escape to exit. Both faces show system-local time.
+`make clock-example` builds it without starting a window.
+
+The [Breakout game](Breakout.smp) has 24 columns and 8 rows, with colors and
+point values by depth: 1 at the bottom through 8 at the top, 864 points total.
+Clear the wall before losing all three balls. Mouse movement or the arrow keys
+move the paddle; Space/left click serves, P pauses, R restarts, Q/Escape exits.
+Run `make run-breakout` or build only with `make breakout`.
+The familiar paddle, serve, and limited-ball rules follow
+[Atari's Breakout instructions](https://atari.com/pages/breakout).
+
+The deepest row reached with the current ball sets the base speed: 320 pixels/second plus 35 for
+each additional depth. After touching the back wall, hitting the top of a brick
+activates a **one-time 1.65x speed boost**; side/front hits do not. Returning to
+the paddle disarms that trip's back-wall opportunity. Losing a ball resets depth
+and boost, so each new ball starts at 320 pixels/second and can earn its own
+back-wall boost. Edge hits on the paddle give a wider
+rebound than center hits. Clear all bricks to win; no new wall replaces them.
+
+Physics uses fixed 8 ms ticks with movement split into steps of at most two
+pixels, including at boosted speed. Rendering runs roughly every 16 ms. The
+brick and sound tables demonstrate array initializers; the short bounce tones
+use read-only PCM arrays made by index functions. Brick boops rise in pitch with
+row depth, from about 333 Hz at the bottom to 800 Hz at the top. Audio is optional. Native
+tests in `BreakoutTest` exercise collisions, scoring, lives, pause, paddle angles,
+the boost, and clearing the whole wall without a display or audio device.
+
+From `chapter31`, build the tic-tac-toe executable (without starting it):
+
+```sh
+make lib tictactoe
+```
+
+Run the Windows build from PowerShell:
+
+```powershell
+.\build\examples\x86_64_v2_win64\TicTacToe.exe
+```
+
+Or from Command Prompt (`cmd.exe`):
+
+```bat
+.\build\examples\x86_64_v2_win64\TicTacToe.exe
+```
+
+Or from Bash (Cygwin, using the Windows build):
+
+```bash
+./build/examples/x86_64_v2_win64/TicTacToe.exe
+```
+
+The Windows executable uses Cygwin's runtime; its `bin` directory must be on
+`PATH` (as it is when building with Cygwin GCC).
+
+For a native Linux build, run these commands from this same `chapter31`
+directory in WSL. Separate Java and native output directories let the Windows
+and Linux builds coexist:
+
+```sh
+make lib tictactoe CLZDIR=build/classes-linux
+./build/examples/x86_64_v2_SystemV/TicTacToe
+```
+
+From PowerShell, prefix either command with `wsl -d Ubuntu-24.04 --`.
+On a standalone Linux checkout, `CLZDIR` can be omitted.
+The compiler's `--link` option produces an executable without running it;
+`--norun` continues to produce object files only.
+
+`TicTacToe.smp` currently prints the welcome, square numbering, and empty board,
+then waits for a move. Press **1–9** without Enter to place X, or
+**q**, Escape, Ctrl-C, or Ctrl-D to quit. Enter is silently ignored; other
+invalid keys and occupied squares prompt again without taking a turn. The board
+is printed after each player and CPU move; only accepted move digits are echoed.
+Play continues until someone wins or the board is
+full. The CPU takes an immediate win, blocks an immediate loss, then prefers
+the center, corners, and edges.
+
+Other examples are Hello World (`A_helloWorld.smp`), `BubbleSort.smp`,
+`Capitalize.smp`, `Dijkstra.smp`, and `FileIO.smp`. The latter creates, checks,
+and removes `output.txt` in the working directory.
+
+## Single-keystroke input
+
+`sys.io.getch()` blocks for one byte without terminal editing or echo. It returns
+0–255 for a byte, or -1 for EOF or an error. On -1, `sys.libc.errno()` is
+`sys.libc.EOF` (-1) for end-of-input, otherwise the OS error code.
+Terminal Ctrl-C and Ctrl-D are bytes 3
+and 4, so the application decides how to handle them. Unicode and function keys
+may produce multiple bytes; this is an ASCII-oriented byte API, not a key-event
+decoder.
+
+The small C runtime adapter uses [POSIX terminal modes](https://man7.org/linux/man-pages/man3/termios.3.html),
+including Cygwin on Windows. It restores the saved mode before returning,
+including after an interrupted read. Files and pipes use an ordinary one-byte
+read. `make test CLASS=TerminalInputTest` runs the Java regression tests for
+redirected input, errors, prompt output, Enter, and Escape. Check terminal
+editing, echo, and mode restoration by running the executable in a terminal.
+`make test CLASS=TicTacToeTest` checks complete games, all eight winning lines,
+draws, occupied squares, and CPU blocking.
diff --git a/docs/chapter31/examples/TicTacToe.smp b/docs/chapter31/examples/TicTacToe.smp
new file mode 100644
index 00000000..ee4e3182
--- /dev/null
+++ b/docs/chapter31/examples/TicTacToe.smp
@@ -0,0 +1,132 @@
+// Player is X, CPU is O. Squares are numbered left-to-right, top-to-bottom.
+val main = { u8[~][] args ->
+ sys.io.p("Tic-tac-toe!\nYou are X; the CPU is O. You go first.\n");
+ sys.io.p("Press a square's number (no Enter needed), or q/Esc to quit.\n");
+ sys.io.p("Squares:\n 1 | 2 | 3 \n---+---+---\n 4 | 5 | 6 \n---+---+---\n 7 | 8 | 9 \n\n");
+ val board = new u8[9]{ int i -> ' '; }; // Initialize the board
+ // Draw empty board
+ _draw(board);
+
+ while( true ) {
+ sys.io.p("Your move (1-9): ");
+ // Valid user move 1-9, or 0 for quitting
+ int square = _validMove(board) - 1;
+ if( square < 0 ) return 0;
+ // Set user choice; print board
+ board[square] = 'X';
+ sys.io.p("\n");
+ _draw(board);
+ // A winner?
+ if( _finished(board) ) return 0;
+ // Compute CPU move
+ int reply = _cpu(board);
+ // Set CPU choice; print board
+ board[reply] = 'O';
+ sys.io.p("CPU plays %(reply+1).\n");
+ _draw(board);
+ // A winner?
+ if( _finished(board) ) return 0;
+ }
+};
+
+// Return with a valid user move 1-9, or 0 to exit
+val _validMove = { u8[~] board ->
+ while( true ) {
+ int key = sys.io.getch();
+ if( key == -1 && sys.libc.errno() != sys.libc.EOF ) {
+ sys.io.err("\nUnable to read the keyboard.\n");
+ return 0;
+ }
+ // Various quitting conditions
+ if( key == -1 || key == 'q' || key == 'Q' || key == 27 || key == 3 || key == 4 ) {
+ sys.io.p("\nGoodbye!\n");
+ return 0;
+ }
+ // Ignore CR/LF
+ if( key == '\r' || key == '\n' ) continue;
+
+ // Valid choice
+ if( key < '1' || key > '9' ) {
+ sys.io.p("\nChoose a square from 1 to 9: ");
+ continue;
+ }
+ if( board[key-'1'] != ' ' ) {
+ sys.io.p("\nThat square is occupied. Your move (1-9): ");
+ continue;
+ }
+ sys.io.p("%c(key)");
+ return key-'0';
+ }
+};
+
+// Return the winning mark, or zero.
+val _winner = { u8[~] board ->
+ for( int i = 0; i < 3; i++ ) {
+ int row = i*3;
+ if( board[row] != ' ' && board[row] == board[row+1] && board[row] == board[row+2] )
+ return board[row];
+ if( board[i] != ' ' && board[i] == board[i+3] && board[i] == board[i+6] )
+ return board[i];
+ }
+ if( board[4] != ' ' ) {
+ if( board[0] == board[4] && board[4] == board[8] ) return board[4];
+ if( board[2] == board[4] && board[4] == board[6] ) return board[4];
+ }
+ return 0;
+};
+
+val _finished = { u8[~] board ->
+ int winner = _winner(board);
+ if( winner == 'X' ) { sys.io.p("You win!\n"); return true; }
+ if( winner == 'O' ) { sys.io.p("CPU wins!\n"); return true; }
+ for( int i = 0; i < board#; i++ )
+ if( board[i] == ' ' ) return false;
+ sys.io.p("It's a draw!\n");
+ return true;
+};
+
+// Try each empty square, restoring it before returning.
+val _threat = { u8[] board, u8 mark ->
+ for( int i = 0; i < board#; i++ ) {
+ if( board[i] == ' ' ) {
+ board[i] = mark;
+ bool wins = _winner(board) == mark;
+ board[i] = ' '; // Restore board
+ if( wins ) return i;
+ }
+ }
+ return -1;
+};
+
+// Win if possible, otherwise block, then prefer center, corners, and edges.
+// Called only after _finished has ruled out a full board.
+val _cpu = { u8[] board ->
+ // If O can win, do so
+ int win = _threat(board,'O');
+ if( win >= 0 ) return win;
+ // If X will win next move, block
+ int block = _threat(board,'X');
+ if( block >= 0 ) return block;
+ // If center is open, take it
+ if( board[4] == ' ' ) return 4;
+ // If a corner is open, take it
+ for( int i = 0; i < board#; i += 2 )
+ if( board[i] == ' ' ) return i;
+ // Take whatever is available
+ for( int i = 0; i < board#; i++ )
+ if( board[i] == ' ' ) return i;
+ return -1;
+};
+
+val _draw = { u8[~] board ->
+ val out = new sys.aryu8();
+ for( int row = 0; row < 3; row++ ) {
+ for( int col = 0; col < 3; col++ ) {
+ out.add(' ').add(board[row*3+col]).add(' ');
+ if( col < 2 ) out.add('|');
+ }
+ out.add('\n');
+ if( row < 2 ) out.addAry("---+---+---\n");
+ }
+ out.write(sys.libc.STDOUT);
+};
diff --git a/docs/chapter31/examples/TicTacToeGraphical.smp b/docs/chapter31/examples/TicTacToeGraphical.smp
new file mode 100644
index 00000000..72ee6522
--- /dev/null
+++ b/docs/chapter31/examples/TicTacToeGraphical.smp
@@ -0,0 +1,169 @@
+// Player is X, CPU is O. Squares are numbered left-to-right, top-to-bottom.
+// Graphical tic-tac-toe; the same strategy as TicTacToe.smp.
+// Click an empty square or press 1-9. R/Space replays; Q/Escape quits.
+// Pass any argument for a five-poll window smoke test.
+val main = { u8[~][] args ->
+ val screen = new sys.draw.Canvas(600,780);
+ val board = new u8[9];
+ _reset(board);
+ if( sys.gfx.open("Simple tic-tac-toe",screen.width,screen.height) != sys.gfx.OK ) return 1;
+ sys.audio.open(); // Audio is optional; failure leaves the game silent.
+ _draw(screen,board,-1);
+ int result = sys.gfx.presentSize(screen.pixels,screen.width,screen.height);
+ bool mouseHeld = false, keyHeld = false, replayHeld = false;
+ int hover = -1, frames = 0;
+
+ while( result == sys.gfx.OK ) {
+ result = sys.gfx.wait(17);
+ if( result != sys.gfx.OK ) break;
+ if( sys.gfx.key('Q') ) break;
+ bool down = sys.gfx.button(sys.gfx.LEFT);
+ bool replay = sys.gfx.key('R') || sys.gfx.key(' ');
+ bool resized = screen.resize(sys.gfx.width(),sys.gfx.height());
+ int square = _square(screen.localX(sys.gfx.mouseX()),screen.localY(sys.gfx.mouseY()));
+ bool dirty = resized || square != hover;
+ hover = square;
+ if( replay && !replayHeld ) { sys.audio.stop(); _reset(board); dirty = true; }
+ bool digit = false;
+ int choice = down && !mouseHeld ? square : -1;
+ for( int i = 0; i < 9; i++ ) {
+ int key = '1'+i;
+ if( sys.gfx.key(key) ) {
+ digit = true;
+ if( !keyHeld ) choice = i;
+ }
+ }
+ if( !(replay && !replayHeld) && _move(board,choice) ) {
+ sys.audio.play(_sound(board));
+ dirty = true;
+ }
+ mouseHeld = down;
+ keyHeld = digit;
+ replayHeld = replay;
+ if( dirty ) {
+ _draw(screen,board,hover);
+ result = sys.gfx.presentSize(screen.pixels,screen.width,screen.height);
+ }
+ if( args# > 1 && ++frames == 5 ) break;
+ }
+ sys.audio.close();
+ sys.gfx.close();
+ return result == sys.gfx.ERROR ? 1 : 0;
+};
+
+// Called only for an accepted move; invalid input never requests a sound.
+val _sound = { u8[~] board ->
+ int winner = _winner(board);
+ return winner == 'X' ? sys.audio.WIN : winner == 'O' ? sys.audio.LOSE : sys.audio.BOOP;
+};
+
+val _reset = { u8[] board ->
+ for( int i = 0; i < 9; i++ ) board[i] = ' ';
+};
+val _square = { int x, int y ->
+ if( x < 48 || x >= 552 || y < 168 || y >= 672 ) return -1;
+ return (y-168)/168*3+(x-48)/168;
+};
+
+// One player turn followed by one CPU turn. Invalid/finished moves do nothing.
+val _move = { u8[] board, int square ->
+ if( square < 0 || square >= 9 || board[square] != ' ' || _finished(board) ) return false;
+ board[square] = 'X';
+ if( !_finished(board) ) {
+ int reply = _cpu(board);
+ if( reply >= 0 ) board[reply] = 'O';
+ }
+ return true;
+};
+
+val _finished = { u8[~] board ->
+ if( _winner(board) ) return true;
+ for( int i = 0; i < 9; i++ ) if( board[i] == ' ' ) return false;
+ return true;
+};
+
+val _winningLine = { u8[~] board ->
+ for( int i = 0; i < 3; i++ ) {
+ int row = i*3;
+ if( board[row] != ' ' && board[row] == board[row+1] && board[row] == board[row+2] ) return i;
+ if( board[i] != ' ' && board[i] == board[i+3] && board[i] == board[i+6] ) return 3+i;
+ }
+ if( board[4] != ' ' ) {
+ if( board[0] == board[4] && board[4] == board[8] ) return 6;
+ if( board[2] == board[4] && board[4] == board[6] ) return 7;
+ }
+ return -1;
+};
+// Return the winning mark, or zero.
+val _winner = { u8[~] board ->
+ int line = _winningLine(board);
+ return line < 0 ? 0 : line < 3 ? board[line*3] : line < 6 ? board[line-3] : board[4];
+};
+
+// Try each empty square, restoring it before returning.
+val _threat = { u8[] board, u8 mark ->
+ for( int i = 0; i < 9; i++ )
+ if( board[i] == ' ' ) {
+ board[i] = mark;
+ bool wins = _winner(board) == mark;
+ board[i] = ' '; // Restore board
+ if( wins ) return i;
+ }
+ return -1;
+};
+// Win if possible, otherwise block, then prefer center, corners, and edges.
+// Called only after _finished has ruled out a full board.
+val _cpu = { u8[] board ->
+ // If O can win, do so
+ int win = _threat(board,'O');
+ if( win >= 0 ) return win;
+ // If X will win next move, block
+ int block = _threat(board,'X');
+ if( block >= 0 ) return block;
+ // If center is open, take it
+ if( board[4] == ' ' ) return 4;
+ // If a corner is open, take it
+ for( int i = 0; i < 9; i += 2 ) if( board[i] == ' ' ) return i;
+ // Take whatever is available
+ for( int i = 0; i < 9; i++ ) if( board[i] == ' ' ) return i;
+ return -1;
+};
+
+val _draw = { !sys.draw.Canvas screen, u8[~] board, int hover ->
+ u32 background = 0x142e36, paper = 0xf2eddf, ink = 0x35535a;
+ u32 cross = 0xe47b57, ring = 0x248b89, accent = 0xf0c778;
+ int winner = _winner(board);
+ bool finished = _finished(board);
+ screen.clear(background);
+ screen.text(48,34,"TIC TAC TOE",6,paper);
+ screen.fillRect(48,90,504,3,ink);
+ screen.text(48,116,finished ? (winner == 'X' ? "YOU WIN!" : winner == 'O' ? "CPU WINS" : "DRAW") : "YOUR TURN",4,accent);
+ screen.line(428,112,450,134,5,cross).line(450,112,428,134,5,cross);
+ screen.circle(496,123,13,5,0x70c9bf);
+ screen.text(428,145,"YOU",2,0xa2b9b7);
+ screen.text(484,145,"CPU",2,0xa2b9b7);
+ screen.fillRect(48,168,504,504,paper);
+ if( !finished && hover >= 0 && hover < 9 && board[hover] == ' ' )
+ screen.fillRect(48+(hover%3)*168,168+hover/3*168,168,168,0xd9e8de);
+ for( int i = 1; i < 3; i++ ) {
+ screen.fillRect(48+i*168-3,168,6,504,ink);
+ screen.fillRect(48,168+i*168-3,504,6,ink);
+ }
+ for( int i = 0; i < 9; i++ ) {
+ int cx = 132+(i%3)*168, cy = 252+i/3*168;
+ if( board[i] == 'X' )
+ screen.line(cx-38,cy-38,cx+38,cy+38,12,cross).line(cx+38,cy-38,cx-38,cy+38,12,cross);
+ else if( board[i] == 'O' ) screen.circle(cx,cy,48,11,ring);
+ else screen.text(cx-6,cy-10,i == 0 ? "1" : i == 1 ? "2" : i == 2 ? "3" :
+ i == 3 ? "4" : i == 4 ? "5" : i == 5 ? "6" : i == 6 ? "7" : i == 7 ? "8" : "9",4,0x95a59e);
+ }
+ int line = _winningLine(board);
+ if( line >= 0 ) {
+ int first = line < 3 ? line*3 : line < 6 ? line-3 : line == 6 ? 0 : 2;
+ int last = line < 3 ? first+2 : line < 6 ? first+6 : line == 6 ? 8 : 6;
+ screen.line(132+(first%3)*168,252+first/3*168,132+(last%3)*168,252+last/3*168,5,0xeab64e);
+ }
+ screen.text(48,704,"CLICK A SQUARE OR PRESS 1-9",3,paper);
+ screen.text(48,738,"R OR SPACE REPLAY Q OR ESC QUIT",3,0xa2b9b7);
+ screen.rect(48,168,504,504,3,ink);
+};