Pick up japanese transaltionpr262-doc-followups

A bunch of minor README fixes, missing TOC, grammer cleanup

4 files changed, 215 insertions, 24 deletions

diff --git a/chapter17a/README.ja.md b/chapter17a/README.ja.md
index 2bbb632c..057c253b 100644
--- a/chapter17a/README.ja.md
+++ b/chapter17a/README.ja.md
@@ -9,6 +9,8 @@
 
 第16章はオブジェクトにフィールドの初期値を与えます。今度は、どの束縛を再代入でき、どの参照が構築後の書き込みを許すかを区別します。フィールドや配列要素も含め、これらは独立した問いです。第17b章では、同じ規則を使って型推論と代入の短縮形を追加します。
 
+この章の[完全な言語文法](docs/17-grammar.ja.md)はこちらです。
+
 ## 2つの権限
 
 構造体型の前の修飾子はアクセス権限を表します。`!Point` は書き込みを許し、`~Point` は深い読み取り専用ビューを与えます。変数名の直前の修飾子は、その束縛を制御します。`!p` は再代入を許し、`~p` は固定します。空白によって意味は変わりません。
diff --git a/chapter17a/README.md b/chapter17a/README.md
index 97904def..9eb70e83 100644
--- a/chapter17a/README.md
+++ b/chapter17a/README.md
@@ -10,6 +10,8 @@ bindings may be reassigned and which references permit writes after construction
 These are independent questions, including for fields and array elements.
 Chapter 17b will add inference and assignment shortcuts using these same rules.
 
+Here is the [complete language grammar](docs/17-grammar.md) for this chapter.
+
 ## Two permissions
 
 A modifier before a struct type names the access permission: `!Point` permits
diff --git a/chapter17a/docs/17-grammar.ja.md b/chapter17a/docs/17-grammar.ja.md
index 9a71f6d6..7675f837 100644
--- a/chapter17a/docs/17-grammar.ja.md
+++ b/chapter17a/docs/17-grammar.ja.md
@@ -1,16 +1,111 @@
-# 第17a章の文法の追加
+# 第17a章の文法
 
 [English](17-grammar.md) | 日本語
 
-この文書は [原文](17-grammar.md) の日本語訳です。
+```antlrv4
+grammar SimpleLanguage;
 
-式と文の形式は第16章と同じです。宣言に、独立したアクセスと束縛の修飾子を追加します。
+// Name lookup, assignable operands, type compatibility, and access permissions
+// are checked by the compiler in addition to these syntax rules.
+program : statement* EOF ;
 
-```text
-declaration = type binding ("," binding)* ";"
-binding     = ("!" | "~")? identifier ("=" expression)?
-type        = ("!" | "~")? name suffix*
-suffix      = "?" | "[]" | "[~]"
-```
+block : '{' statement* '}' ;
+
+statement
+    : block
+    | returnStatement
+    | ifStatement
+    | whileStatement
+    | breakStatement
+    | continueStatement
+    | structDeclaration
+    | declaration ';'
+    | assignment ';'
+    | ';'
+    ;
+
+returnStatement   : 'return' assignment ';' ;
+ifStatement       : 'if' '(' assignment ')' statement ('else' statement)? ;
+whileStatement    : 'while' '(' assignment ')' statement ;
+breakStatement    : 'break' ';' ;
+continueStatement : 'continue' ';' ;
+
+structDeclaration : 'struct' IDENTIFIER block ';' ;
+
+declaration : declarationType binding (',' binding)* ;
+declarationType : type ;
+binding : bindingModifier? IDENTIFIER ('=' initializer)? ;
+bindingModifier : '!' | '~' ;
+initializer : assignment ;
+
+// The prefix qualifies the named struct reference, not an enclosing array.
+// Each [] / [~] suffix qualifies its own array layer. ? requires a reference.
+type
+    : primitiveType typeSuffix*
+    | accessModifier? typeName typeSuffix*
+    ;
+accessModifier : '!' | '~' ;
+typeSuffix : '?' | '[]' | '[~]' ;
+typeName : IDENTIFIER ;
+
+primitiveType
+    : 'int' | 'i8' | 'i16' | 'i32' | 'i64'
+    | 'u1' | 'u8' | 'u16' | 'u32' | 'byte' | 'bool'
+    | 'flt' | 'f32' | 'f64'
+    ;
+
+assignment : expression (assignmentOperator assignment)? ;
+assignmentOperator : '=' ;
+
+expression : bitwiseExpression ;
+
+bitwiseExpression
+    : comparisonExpression (('&' | '|' | '^') comparisonExpression)*
+    ;
 
-前置の修飾子には構造体参照が必要です。それは名前付きの基本型を修飾し、囲む配列は修飾しません。各角括弧の組は、それぞれ自身の配列の層を修飾します。束縛の修飾子は、その直後の名前だけに適用します。デフォルトとコンストラクタの初期化規則については [README](../README.ja.md) を参照してください。`var`、`val`、インクリメント、複合代入、条件式、`for` ループは第17b章で導入します。
+comparisonExpression
+    : shiftExpression (('==' | '!=' | '<' | '<=' | '>' | '>=') shiftExpression)*
+    ;
+
+shiftExpression
+    : additiveExpression (('<<' | '>>' | '>>>') additiveExpression)*
+    ;
+
+additiveExpression
+    : multiplicativeExpression (('+' | '-') multiplicativeExpression)*
+    ;
+
+multiplicativeExpression
+    : unaryExpression (('*' | '/') unaryExpression)*
+    ;
+
+unaryExpression
+    : ('-' | '!') unaryExpression
+    | postfixExpression
+    ;
+
+postfixExpression : primaryExpression postfixSuffix* ;
+postfixSuffix : '.' IDENTIFIER | '[' assignment ']' | '#' ;
+
+primaryExpression
+    : INTEGER_LITERAL
+    | FLOAT_LITERAL
+    | 'true'
+    | 'false'
+    | 'null'
+    | IDENTIFIER
+    | '(' assignment ')'
+    | newExpression
+    ;
+
+// Struct initialization uses a block; array allocation supplies a length.
+newExpression : 'new' type ('[' assignment ']' | block)? ;
+
+INTEGER_LITERAL : '0' | [1-9] DIGIT* ;
+FLOAT_LITERAL : DIGIT+ ('.' DIGIT* ('e' DIGIT+)? | 'e' DIGIT+) ;
+IDENTIFIER : NON_DIGIT (NON_DIGIT | DIGIT)* ;
+fragment NON_DIGIT : [a-zA-Z_] ;
+fragment DIGIT : [0-9] ;
+WHITESPACE : [ \t\r\n]+ -> skip ;
+LINE_COMMENT : '//' ~[\r\n]* -> skip ;
+```
diff --git a/chapter17a/docs/17-grammar.md b/chapter17a/docs/17-grammar.md
index a8cd8818..52afb324 100644
--- a/chapter17a/docs/17-grammar.md
+++ b/chapter17a/docs/17-grammar.md
@@ -1,19 +1,111 @@
-# Chapter 17a grammar additions
+# Grammar for Chapter 17a
 
 English | [日本語](17-grammar.ja.md)
 
-The expression and statement forms are those of Chapter 16. Declarations add
-independent access and binding modifiers:
+```antlrv4
+grammar SimpleLanguage;
 
-```text
-declaration = type binding ("," binding)* ";"
-binding     = ("!" | "~")? identifier ("=" expression)?
-type        = ("!" | "~")? name suffix*
-suffix      = "?" | "[]" | "[~]"
-```
+// Name lookup, assignable operands, type compatibility, and access permissions
+// are checked by the compiler in addition to these syntax rules.
+program : statement* EOF ;
+
+block : '{' statement* '}' ;
+
+statement
+    : block
+    | returnStatement
+    | ifStatement
+    | whileStatement
+    | breakStatement
+    | continueStatement
+    | structDeclaration
+    | declaration ';'
+    | assignment ';'
+    | ';'
+    ;
+
+returnStatement   : 'return' assignment ';' ;
+ifStatement       : 'if' '(' assignment ')' statement ('else' statement)? ;
+whileStatement    : 'while' '(' assignment ')' statement ;
+breakStatement    : 'break' ';' ;
+continueStatement : 'continue' ';' ;
+
+structDeclaration : 'struct' IDENTIFIER block ';' ;
+
+declaration : declarationType binding (',' binding)* ;
+declarationType : type ;
+binding : bindingModifier? IDENTIFIER ('=' initializer)? ;
+bindingModifier : '!' | '~' ;
+initializer : assignment ;
+
+// The prefix qualifies the named struct reference, not an enclosing array.
+// Each [] / [~] suffix qualifies its own array layer. ? requires a reference.
+type
+    : primitiveType typeSuffix*
+    | accessModifier? typeName typeSuffix*
+    ;
+accessModifier : '!' | '~' ;
+typeSuffix : '?' | '[]' | '[~]' ;
+typeName : IDENTIFIER ;
+
+primitiveType
+    : 'int' | 'i8' | 'i16' | 'i32' | 'i64'
+    | 'u1' | 'u8' | 'u16' | 'u32' | 'byte' | 'bool'
+    | 'flt' | 'f32' | 'f64'
+    ;
+
+assignment : expression (assignmentOperator assignment)? ;
+assignmentOperator : '=' ;
+
+expression : bitwiseExpression ;
 
-A prefix qualifier requires a struct reference. It qualifies the named base,
-not enclosing arrays. Each bracket pair qualifies its own array layer. A binding
-modifier applies only to the following name. See the README for defaults and
-constructor initialization rules. `var`, `val`, increments, compound assignments,
-conditional expressions, and `for` loops are introduced in Chapter 17b.
+bitwiseExpression
+    : comparisonExpression (('&' | '|' | '^') comparisonExpression)*
+    ;
+
+comparisonExpression
+    : shiftExpression (('==' | '!=' | '<' | '<=' | '>' | '>=') shiftExpression)*
+    ;
+
+shiftExpression
+    : additiveExpression (('<<' | '>>' | '>>>') additiveExpression)*
+    ;
+
+additiveExpression
+    : multiplicativeExpression (('+' | '-') multiplicativeExpression)*
+    ;
+
+multiplicativeExpression
+    : unaryExpression (('*' | '/') unaryExpression)*
+    ;
+
+unaryExpression
+    : ('-' | '!') unaryExpression
+    | postfixExpression
+    ;
+
+postfixExpression : primaryExpression postfixSuffix* ;
+postfixSuffix : '.' IDENTIFIER | '[' assignment ']' | '#' ;
+
+primaryExpression
+    : INTEGER_LITERAL
+    | FLOAT_LITERAL
+    | 'true'
+    | 'false'
+    | 'null'
+    | IDENTIFIER
+    | '(' assignment ')'
+    | newExpression
+    ;
+
+// Struct initialization uses a block; array allocation supplies a length.
+newExpression : 'new' type ('[' assignment ']' | block)? ;
+
+INTEGER_LITERAL : '0' | [1-9] DIGIT* ;
+FLOAT_LITERAL : DIGIT+ ('.' DIGIT* ('e' DIGIT+)? | 'e' DIGIT+) ;
+IDENTIFIER : NON_DIGIT (NON_DIGIT | DIGIT)* ;
+fragment NON_DIGIT : [a-zA-Z_] ;
+fragment DIGIT : [0-9] ;
+WHITESPACE : [ \t\r\n]+ -> skip ;
+LINE_COMMENT : '//' ~[\r\n]* -> skip ;
+```