merge line tables

1 files changed, 14 insertions, 5 deletions

diff --git a/docs/SPEC.md b/docs/SPEC.md
index 3ad93c8..5618a5e 100644
--- a/docs/SPEC.md
+++ b/docs/SPEC.md
@@ -74,7 +74,7 @@ a name that looks like `x.y` where `x` is not a known module is the three tokens
 
 a keyword marked only S used inside an expression is the error `NAME: can't be used inside an expression`. a keyword that is not E and is used where an expression is expected is the same error.
 
-1.3.5 these words are recognised by position by the parser, are not in the keyword table, and are treated as ordinary names elsewhere: `fn`, `const`, `fixed`, `static`, `struct`, `type`, `typecheck`, `docs`, `namespace`, `enhance`, `immediate`, `as`, `case`, `default`, `on`, `off`, `small`, `micro`, `vm`, `this`, `new`, and the tag names `u`, `m`, `d`. `struct`, `type`, `typecheck`, `docs`, `namespace` and `enhance` are top-level only (5.1.2).
+1.3.5 these words are recognised by position by the parser, are not in the keyword table, and are treated as ordinary names elsewhere: `fn`, `const`, `fixed`, `static`, `struct`, `type`, `typecheck`, `docs`, `lines`, `namespace`, `enhance`, `immediate`, `as`, `case`, `default`, `on`, `off`, `small`, `micro`, `vm`, `this`, `new`, and the tag names `u`, `m`, `d`. `struct`, `type`, `typecheck`, `docs`, `namespace` and `enhance` are top-level only (5.1.2).
 
 1.3.6 the type names `int word char bool void float f64 f32 bstr i8 u8 byte i16 u16 i32 u32` are ordinary names bound to types (2.1). a local variable with such a name shadows the type name where a declaration or expression could start.
 
@@ -659,9 +659,9 @@ int y = 7; asm { y @ 1 + y ! }    // y is 8
 
 ### 5.1 items
 
-5.1.1 a unit is a sequence of items. an item is: a function definition or prototype, a global variable, `const`, `struct`, `type`, `enum`, `include`, `embed`, `namespace`, `typecheck`, `docs`, `memdebug`, `hints`, `enhance`, `extern`, `unchecked;`, or a use of a top-level parse word (7.2).
+5.1.1 a unit is a sequence of items. an item is: a function definition or prototype, a global variable, `const`, `struct`, `type`, `enum`, `include`, `embed`, `namespace`, `typecheck`, `docs`, `lines`, `memdebug`, `hints`, `enhance`, `extern`, `unchecked;`, or a use of a top-level parse word (7.2).
 
-5.1.2 `struct`, `type`, `typecheck`, `docs`, `namespace`, `enhance` and `extern` are valid only at the top level. `enum`, `embed`, `memdebug`, `hints` and `const` also appear as statements in functions. `include` is top-level only (5.12.7).
+5.1.2 `struct`, `type`, `typecheck`, `docs`, `lines`, `namespace`, `enhance` and `extern` are valid only at the top level. `enum`, `embed`, `memdebug`, `hints` and `const` also appear as statements in functions. `include` is top-level only (5.12.7).
 
 5.1.3 the unit is scanned once for function signatures before it is compiled, so calls may precede definitions and prototypes are optional (an untyped function called before its tags are declared that later declares `.m`/`.d` tags is error: f: was called before its tags were declared; put a prototype above the first call).
 
@@ -787,6 +787,14 @@ rt.put_n(util.twice(1));        // error: module access requires `include util;`
 
 `docs on;` keeps doc comments of what follows in the image; `docs off;` stops. no effect on a program's behaviour.
 
+### 5.15 lines
+
+5.15.1 `lines on;` records a line table for each function, method, closure and evaluated unit compiled after it; `lines off;` stops. a program starts with lines on. `lines` followed by anything other than `on` or `off` is an ordinary name.
+
+5.15.2 a line table changes no result of a program, only what a trace prints (8.4). a function compiled with lines off shows in a trace by its address and nearest name, or not at all when it belongs to the genome.
+
+5.15.3 the comment `//:lines NAME` names the source after it NAME, counts its lines from the next line, and turns lines on from the next top-level item.
+
 ## 6. ownership and lifetimes
 
 this section describes the analyzer: a pass that runs inside the compiler on every function (including code compiled at run time by `run.eval` and friends), tracks heap objects through local variables, inserts frees, and reports violations. it can be switched off (6.12). what it proves is limited to what is stated here.
@@ -1050,19 +1058,20 @@ each error is a line `zc: line N: MESSAGE`. after the unit, a summary line `zc:
 | `rt.len_w(s)`, `rt.eq_w(a, b)`, `rt.copy_w(dst, src, n)`, `rt.fill_w(dst, v, n)` | word-string length, equality, word copy, word fill |
 | `rt.len_s rt.at_s rt.slice_s rt.cat_s rt.eq_s rt.s_to_n rt.n_to_s rt.put_bs` | packed byte strings |
 | `rt.gc() rt.memreport() rt.syscall rt.readfile` | collector, leak report, host gate, file read |
+| `rt.trace()` | write the current call stack, innermost call first, one line `  at FILE:LINE in NAME` per frame with a line table (8.4); returns 0 |
 
 heap objects have a 5 word header before the pointer (size, flags, check word, owner, type); `rt.new` words are zeroed. output is the process's standard output, one byte per `put_c`.
 
 ### 8.4 run-time errors
 
-the program prints `zy: index I out of range (length N)` and stops on an out-of-range `T[?]` index; `zy: use after free from line N`, `zy: double free from line N`, `zy: bad heap pointer` under `memdebug`. the machine does not trap on integer division by zero (3.4.3) or on a stray write inside memory.
+the program prints `zy: index I out of range (length N)` and stops on an out-of-range `T[?]` index; `zy: use after free from line N`, `zy: double free from line N`, `zy: bad heap pointer` under `memdebug`. these reports, `zc: out of heap memory` and a frame overflow are followed by the call stack in the form `rt.trace()` prints (5.15); a frame without a line table shows as `  at 0xADDR in NAME`, frames of the genome are left out, and a stack of more than 28 frames shows the innermost 24, `  ... N more frames` and the outermost 4. the machine does not trap on integer division by zero (3.4.3) or on a stray write inside memory.
 
 ## appendix a: what zc0 accepts
 
 zc0 (`src/tools/zc0.c`) is the stage-0 bootstrap compiler. it reads source on stdin and writes a genome image; to run a program through it use `make run PROG=file.zc` (the source starts with `namespace;` and defines `main`). it has no types (they are read and dropped), no analyzer, no checks. in the zc0 subset:
 
 - lexing: comments, decimal/hex integers (but see appendix b for octal and saturation), floats, character literals, word strings, `b"..."`, the operator set `== != <= >= << >> && || ++ -- += -= *= /= %= &= |= ^= -> <<= >>=`, the source-ending backtick, `rt.`/`run.`/`core.`/`lsp.`/`std.`/`icon.` joined names.
-- top level: `namespace`, `include` (the names are read and ignored; resident modules only), `embed`, `unchecked`, `fn`, `.u name(...)`, typed functions and globals, `const`, `enhance`, `let`/`var` globals, prototypes.
+- top level: `namespace`, `include` (the names are read and ignored; resident modules only), `embed`, `unchecked`, `lines on;`/`lines off;` and the `//:lines NAME` comment (line tables as in 5.15), `fn`, `.u name(...)`, typed functions and globals, `const`, `enhance`, `let`/`var` globals, prototypes.
 - statements: blocks, declarations (typed or `let`/`var`, arrays `x[n]` and `T[n]`), `unchecked stmt`, `if`/`else`, `while`, `for`, `break`, `continue`, `return`, `asm`, expression statements.
 - expressions: all binary operators with the c precedences, assignment and compound assignment, unary `- ! ~ * & ++ --`, recasts `u*x m*x d*x` (no code), postfix `[]`, `[i:j]` and `[i]` on byte strings, calls (including through a value), `++ --`, `x as name`, `asm { }`, float arithmetic and comparisons, byte strings (`+`, comparisons).