From 2c03860df2037e90860a2ca02a4f8c7eaeb48e12 Mon Sep 17 00:00:00 2001 From: InauguralPhysicist Date: Tue, 7 Jul 2026 19:37:15 -0500 Subject: [PATCH] docs: fix the four front-door examples that misrepresented the language MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README and doc examples a newcomer reads first were wrong on the exact surfaces we lead with. Verified every corrected example against the real runtime (byte-true output shown): - README observer example (#313): `5,2,5,2` classified as `diverging`, not the claimed `oscillating` — four samples is too short. Extended to three periods (`5,2,5,2,5,2`) so it truly prints `oscillating`. This is the showcase of the observer, our whole differentiator; it printed the wrong trajectory. - README stdlib snippet (#319): `map of [[1,2,3], double]` referenced an undefined `double` and crashed with `undefined variable 'double'` on a reader's first copy-paste. Now defines `double` inline; prints [2,4,6]. - lib/format.eigs fmt_bar docstring (#320): showed `████░░░░░░`; actual output is `[######....] 60.0%`. Docstring now matches the runtime. - String-escape docs (#318): SYNTAX/GRAMMAR/LANGUAGE_CONTRACT implied a closed escape set `\n \t \r \\ \" \{ \}`. The lexer recognizes `\n \t \r \\ \"` and drops the backslash on any other `\x` (so `\{`/`\}` give literal braces via the catch-all, and `\r` was real but only documented in the contract). Docs now state the true contract. Docs-only; doc_drift_check.sh passes. Closes #313 Closes #319 Closes #320 Closes #318 Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 8 ++++++-- docs/GRAMMAR.md | 4 +++- docs/LANGUAGE_CONTRACT.md | 4 +++- docs/SYNTAX.md | 4 ++++ lib/format.eigs | 2 +- 5 files changed, 17 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 271cece..c260d36 100644 --- a/README.md +++ b/README.md @@ -145,7 +145,9 @@ reading is 5.0 reading is 2.0 reading is 5.0 reading is 2.0 -report of reading # "oscillating" +reading is 5.0 +reading is 2.0 +report of reading # "oscillating" (needs a few periods to classify) ``` Trajectory states: `converged`, `stable`, `equilibrium`, `oscillating`, @@ -269,7 +271,9 @@ Pure EigenScript libraries under `lib/`: ```eigenscript load_file of "lib/list.eigs" -doubled is map of [[1,2,3], double] +define double as: # functions take one argument, n + return n * 2 +doubled is map of [[1, 2, 3], double] # [2, 4, 6] ``` See [docs/STDLIB.md](docs/STDLIB.md) for the full library guide. diff --git a/docs/GRAMMAR.md b/docs/GRAMMAR.md index 0886192..21b3d30 100644 --- a/docs/GRAMMAR.md +++ b/docs/GRAMMAR.md @@ -47,7 +47,9 @@ COMMENT = '#' { any } '\n' letter = 'a'..'z' | 'A'..'Z' digit = '0'..'9' -escape = '\n' | '\t' | '\r' | '\\' | '\"' | '\{' | '\}' +escape = '\n' | '\t' | '\r' | '\\' | '\"' | '\' any + # only n t r \ " are special; any other '\x' yields literal x + # (so '\{' and '\}' give literal braces) ``` ### Keywords diff --git a/docs/LANGUAGE_CONTRACT.md b/docs/LANGUAGE_CONTRACT.md index 5ba5e6f..fe3459b 100644 --- a/docs/LANGUAGE_CONTRACT.md +++ b/docs/LANGUAGE_CONTRACT.md @@ -118,7 +118,9 @@ examples (executed by the suite). byte-offset operations — this is the documented consequence of the byte model, not a bug. - Strings are immutable; comparison (`==`, `<`) is bytewise. -- String literals support the escapes `\n \t \r \\ \" \{ \}`. There is no `\0`, +- String literals recognize the escapes `\n \t \r \\ \"`; any other `\x` + yields the literal character `x` (the backslash is dropped) — this is how + `\{` and `\}` produce literal braces in f-strings. There is no `\0`, `\xNN`, or `\u{…}` escape, so a string cannot embed a NUL or an arbitrary byte from source (only the raw bytes present in the source file flow through). An embedded NUL, if one ever arrived from file/buffer input, diff --git a/docs/SYNTAX.md b/docs/SYNTAX.md index 902d22a..f6634e4 100644 --- a/docs/SYNTAX.md +++ b/docs/SYNTAX.md @@ -135,6 +135,10 @@ print of f"list length: {len of items}" Expressions inside `{}` are evaluated and converted to strings. Use `\{` and `\}` for literal braces. +Both plain and `f` strings recognize the escapes `\n`, `\t`, `\r`, `\\`, and +`\"`. Any other `\x` yields the literal character `x` (the backslash is +dropped) — which is exactly why `\{` and `\}` produce literal braces. + ## Interactive REPL Run `eigenscript` with no arguments to enter the REPL: diff --git a/lib/format.eigs b/lib/format.eigs index 314bb7c..5f388bb 100644 --- a/lib/format.eigs +++ b/lib/format.eigs @@ -8,7 +8,7 @@ # fmt_num of [value, decimals] # "3.14" # fmt_percent of [0.856, 1] # "85.6%" # fmt_table of [headers, rows] # aligned text table -# fmt_bar of [value, max_val, width] # "████░░░░░░" +# fmt_bar of [6, 10, 10] # "[######....] 60.0%" # fmt_padded of [value, width] # right-aligned in field # ---- fmt_num: format number to fixed decimal places ----