plainscript-lang 1.0.362 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/README.md +394 -54
  2. package/compiler/bundler.js +78 -3
  3. package/compiler/cli.js +239 -30
  4. package/compiler/formatter.js +21 -1
  5. package/compiler/generator.js +453 -107
  6. package/compiler/ir.js +62 -0
  7. package/compiler/lexer.js +42 -7
  8. package/compiler/lsp.js +290 -0
  9. package/compiler/parser.js +820 -113
  10. package/compiler/type-checker.js +440 -0
  11. package/compiler/version.js +1 -1
  12. package/docs/CAPABILITY_GAP_AUDIT.md +19 -3
  13. package/docs/GAME-PROMPT.md +3 -3
  14. package/docs/PLAINSCRIPT-GRAMMAR.md +317 -0
  15. package/docs/PLAINSCRIPT-SPEC.md +264 -5
  16. package/docs/V1.1-TYPED-COLLECTIONS-DESIGN.md +220 -0
  17. package/docs/index.html +5 -5
  18. package/docs/website/script.js +1 -1
  19. package/examples/ai-memory-cli.pln +221 -0
  20. package/examples/ai-memory.json +1 -0
  21. package/examples/ai-providers.pln +1 -1
  22. package/examples/arrays.pln +1 -1
  23. package/examples/async-errors.pln +1 -1
  24. package/examples/auth-api.pln +1 -1
  25. package/examples/auth-sessions.pln +1 -1
  26. package/examples/basics.pln +1 -1
  27. package/examples/bots.pln +1 -1
  28. package/examples/browser-interactive/README.md +1 -1
  29. package/examples/browser-interactive/src/interactive.pln +1 -1
  30. package/examples/cache-and-jobs.pln +1 -1
  31. package/examples/cache-schedule.pln +1 -1
  32. package/examples/canvas-game/README.md +1 -1
  33. package/examples/canvas-game/src/game.pln +1 -1
  34. package/examples/collections.pln +1 -1
  35. package/examples/compound-assignments.pln +24 -0
  36. package/examples/concurrency.pln +2 -2
  37. package/examples/conditions.pln +1 -1
  38. package/examples/database.pln +1 -1
  39. package/examples/day2.pln +1 -1
  40. package/examples/day3.pln +1 -1
  41. package/examples/deployment.pln +1 -1
  42. package/examples/email-send.pln +1 -1
  43. package/examples/error-handling.pln +1 -1
  44. package/examples/expressions.pln +1 -1
  45. package/examples/file-manager-cli.pln +51 -0
  46. package/examples/file-uploads.pln +1 -1
  47. package/examples/files-and-config.pln +1 -1
  48. package/examples/files.pln +1 -1
  49. package/examples/football-backend/app.pln +1 -1
  50. package/examples/functions.pln +1 -1
  51. package/examples/hello.pln +1 -1
  52. package/examples/http-client.pln +1 -1
  53. package/examples/http.pln +1 -1
  54. package/examples/id-verification/app.pln +1 -1
  55. package/examples/interactive-cli.pln +34 -0
  56. package/examples/javascript-library/README.md +1 -1
  57. package/examples/javascript-library/src/interop.pln +1 -1
  58. package/examples/json.pln +1 -1
  59. package/examples/loops.pln +1 -1
  60. package/examples/memoize-demo.pln +31 -0
  61. package/examples/modules/app.pln +1 -1
  62. package/examples/modules/main.pln +1 -1
  63. package/examples/modules/math.pln +1 -1
  64. package/examples/mongo.pln +1 -1
  65. package/examples/normalization-forms.pln +22 -0
  66. package/examples/objects.pln +1 -1
  67. package/examples/ocr.pln +1 -1
  68. package/examples/packages.pln +1 -1
  69. package/examples/random-cli.pln +32 -0
  70. package/examples/record-kinds.pln +1 -1
  71. package/examples/records.pln +1 -1
  72. package/examples/rest-api-fetch.pln +1 -1
  73. package/examples/rest-api.pln +1 -1
  74. package/examples/run-in-parallel.pln +25 -0
  75. package/examples/scheduled-tasks.pln +1 -1
  76. package/examples/search-and-filter.pln +1 -1
  77. package/examples/server.pln +1 -1
  78. package/examples/sessions-and-cookies.pln +1 -1
  79. package/examples/sqlite.pln +1 -1
  80. package/examples/start.pln +1 -1
  81. package/examples/stats-cli.pln +29 -0
  82. package/examples/stdlib.pln +1 -1
  83. package/examples/string-helpers.pln +23 -0
  84. package/examples/string-verbs.pln +1 -1
  85. package/examples/telegram-ai-bot.pln +1 -1
  86. package/examples/telegram-bot.pln +1 -1
  87. package/examples/terminal-cli.pln +11 -0
  88. package/examples/testing.pln +1 -1
  89. package/examples/three-dimensional/README.md +1 -1
  90. package/examples/three-dimensional/src/scene.pln +1 -1
  91. package/examples/todo-cli.pln +98 -0
  92. package/examples/typed-collections.pln +21 -0
  93. package/examples/web-api.pln +1 -1
  94. package/examples/web-app.pln +1 -1
  95. package/examples/websocket-server.pln +1 -1
  96. package/examples/websocket.pln +1 -1
  97. package/examples/whatsapp-bot/pairing.pln +1 -1
  98. package/examples/whatsapp-bot/qr.pln +1 -1
  99. package/package.json +13 -4
@@ -0,0 +1,317 @@
1
+ # PlainScript Grammar Reference
2
+
3
+ This document is the single source of truth for the PlainScript language
4
+ surface. Compiler behavior (`compiler/lexer.js`, `compiler/parser.js`,
5
+ `compiler/generator.js`) overrides any prose in this or other docs.
6
+
7
+ Version: 1.0.363
8
+
9
+ ---
10
+
11
+ ## 1. Files and encoding
12
+
13
+ A `.pln` file is UTF-8 text. Line comments start with `//`. Blank lines are
14
+ ignored. Indentation is conventional and ignored by the lexer; blocks are
15
+ *keyword* delimited, not indentation delimited.
16
+
17
+ ## 2. Tokens and keywords
18
+
19
+ PlainScript is lexed into tokens first. Almost every line begins with a
20
+ keyword; the parser dispatches statements off the first token. The full
21
+ keyword set:
22
+
23
+ ```text
24
+ remember let show print display as is if otherwise else done end
25
+ do greater less than make define function give return give back
26
+ becomes is now set to change to for each every in while use
27
+ import include load when someone visits listen start on serve on
28
+ on reply respond send back json file serve serve static serve public
29
+ folder above below at least most not empty contains starts ends
30
+ with between and or instanceof now back true false null undefined
31
+ web route start run on database connect database use database
32
+ ask prompt ocr gather filter total match against pattern parallel
33
+ stream emit happens catches yield symbol debugger to together be
34
+ then plus minus times divided by list with record with raise raises
35
+ choosing uses fills repeat until log query insert update delete
36
+ execute
37
+ ```
38
+
39
+ Some keywords are contextual: `end` is a universal block terminator (an alias
40
+ for `done`); `most` only forms a comparator as `is at most`.
41
+
42
+ ### Reserved words: names you cannot declare
43
+
44
+ You cannot use a keyword as a variable, function, or parameter name. This
45
+ includes (non-exhaustively): `log`, `start`, `empty`,
46
+ `pattern`, `match`, `filter`, `gather`, `stream`, `emit`, `run`,
47
+ `then`, `to`, `file`*, `load`, `route`, `database`, `raise`, `retry`,
48
+ `between`, `contains`, `with`, `and`, `or`, `not`.
49
+
50
+ \* `file` is accepted as a variable name by `remember` but not as a
51
+ function name. `back`, `total`, `reply`, `respond`, `send` and the SQL words
52
+ (`query`, `insert`, `update`, `delete`, `execute`) are contextual and *are*
53
+ accepted as declaration names where unambiguous.
54
+
55
+ When a reserved word is used as a name, the compiler reports a clean error
56
+ naming the word, e.g.:
57
+
58
+ ```text
59
+ Line 1, Column 10: Expected a variable name after "remember".
60
+
61
+ "log" is a reserved PlainScript word and cannot be used as a name here.
62
+ Pick a different name (see docs/PLAINSCRIPT-GRAMMAR.md).
63
+ ```
64
+
65
+ ### Operators
66
+
67
+ | Token | Meaning |
68
+ |---|---|
69
+ | `+ - * / %` | arithmetic |
70
+ | `**` | exponentiation |
71
+ | `plus`, `minus`, `times`, `divided by` | word-form arithmetic |
72
+ | `->` | case arrow / lambda arrow |
73
+ | `.` `?.` `??` | member access, optional chain, nullish coalesce |
74
+ | `...` | spread |
75
+ | `(` `)` `[` `]` `{` `}` `,` `:` | grouping, literals, comma, object colon |
76
+
77
+ ### Assignment operators
78
+
79
+ | Operator | Meaning |
80
+ |---|---|
81
+ | `=` | never used as a token; assignments are word-formed (see §4) |
82
+ | `+=` | add-assign (lexed as `PLUS_ASSIGN`; the legacy spelling `++=` is accepted and normalized) |
83
+ | `-=` | subtract-assign |
84
+ | `*=` | multiply-assign |
85
+ | `/=` | divide-assign |
86
+ | `%=` | remainder-assign |
87
+ | `\|\|=` | logical-or assign (word form: `or becomes`) |
88
+ | `&&=` | logical-and assign (word form: `and becomes`) |
89
+ | `??=` | nullish assign (word form: `nullish becomes`) |
90
+
91
+ ## 3. Literals
92
+
93
+ ```plainscript
94
+ remember zero as 0
95
+ remember negative as -5
96
+ remember pi as 3.14
97
+ remember hex as 0xFF
98
+ remember big as 1n
99
+ remember quoted as "double-quoted string"
100
+ remember templated as `template ${interpolation}`
101
+ remember truth as true
102
+ remember falsity as false
103
+ remember nothing as null
104
+ remember absent as undefined
105
+ remember arr as [1, 2, 3]
106
+ remember arr2 as list with 1, 2, 3
107
+ remember obj as { name: "Ada", age: 17 }
108
+ remember rec as record with name "Ada" and age 17
109
+ ```
110
+
111
+ Arrays and records come in both a bracket and a word form; the two normalize
112
+ to the same AST.
113
+
114
+ ### Nullish equality (v1.0.364)
115
+
116
+ `is null` is deliberately **nullish**: it matches `null` *and* `undefined`.
117
+ PlainScript builtins intentionally differ — `env()` of a missing variable
118
+ yields `null`, while reading a missing array slot (e.g. `first of []`)
119
+ yields `undefined` — so a guard written as `is null` must never silently
120
+ fail on the other nullish value:
121
+
122
+ ```plainscript
123
+ remember f as first of []
124
+ if f is null // true — catches null AND undefined
125
+ show "missing"
126
+ done
127
+ ```
128
+
129
+ `is undefined` is the strict escape hatch (matches `undefined` only), and
130
+ comparing the two literals to each other keeps JavaScript semantics
131
+ (`null is undefined` is false). `is not null` is nullish the same way.
132
+
133
+ ### Parser limits
134
+
135
+ Expressions may nest up to 300 levels deep and blocks up to 200 levels deep
136
+ (real code never comes close). Beyond the limit compilation fails with a
137
+ clean positional error — never a JavaScript stack trace. Runtime failures of
138
+ common shapes (calling a non-function, reading a property of a missing value,
139
+ invalid JSON) are translated into PlainScript wording with a hint; run with
140
+ `--sourcemap` to also get the source-mapped `.pln` stack line.
141
+
142
+ ## 4. Variables and assignment
143
+
144
+ ## 4. Variables and assignment
145
+
146
+ Declaration — all three are identical and compile to the same JavaScript:
147
+
148
+ ```plainscript
149
+ let x is 5
150
+ let y be 6
151
+ remember z as 7
152
+ ```
153
+
154
+ Mutable bindings may carry a recursive collection or record contract between
155
+ the name and initializer:
156
+
157
+ ```text
158
+ let users as list of User is [{ id: 1, name: "Ada" }]
159
+ let usersById as dictionary of User is { first: { id: 1, name: "Ada" } }
160
+ ```
161
+
162
+ Reassignment (word-formed; PlainScript has no `=` symbol):
163
+
164
+ ```plainscript
165
+ x becomes 10
166
+ x is now 11
167
+ x set to 12
168
+ x change to 13
169
+ flag or becomes true // flag ||= true
170
+ flag and becomes false // flag &&= false
171
+ val nullish becomes "dflt" // val ??= "dflt"
172
+ ```
173
+
174
+ Prefix aliases (v1.0.363): `set <target> to <value>` and
175
+ `change <target> to <value>` are the prefix forms of the `set to` /
176
+ `change to` assignment above (the target may also be a member or a numbered
177
+ item):
178
+
179
+ ```plainscript
180
+ set x to 10
181
+ change x to 20
182
+ set data at position 0 to 99
183
+ ```
184
+
185
+ Compound arithmetic assignment:
186
+
187
+ ```plainscript
188
+ n += 1 n -= 2 n *= 3 n /= 4 n %= 5
189
+ n ++= 1 // legacy spelling of +=; still accepted and normalized
190
+ ```
191
+
192
+ Destructuring still uses the word form against a bracket/brace pattern:
193
+
194
+ ```plainscript
195
+ remember [a, b] as pair
196
+ remember { x, y } as point
197
+ ```
198
+
199
+ Typed contracts use a contextual `type` declaration. Field annotations are
200
+ required unless they use `optional`; nested collection annotations and simple
201
+ unions are supported.
202
+
203
+ ```plainscript
204
+ type User
205
+ id is number
206
+ name is text
207
+ active is optional boolean
208
+ tags is list of text
209
+ metadata is dictionary of text
210
+ done
211
+
212
+ make greet(user as User)
213
+ give user.name
214
+ done
215
+ ```
216
+
217
+ The generated function validates `user` before entering its body. The static
218
+ checker also validates literal arguments, typed bindings, return contracts,
219
+ collection elements, nested fields, and known member access. It remains
220
+ conservative for expressions whose types are unknown.
221
+
222
+ ## 5. Statements and blocks
223
+
224
+ Blocks open with a keyword line and close with `done` **or** `end`. They are
225
+ equivalent; `end` maps to the same terminator as `done` in the lexer.
226
+
227
+ | Statement | Opens | Closes with |
228
+ |---|---|---|
229
+ | `if <cond>` (with optional `otherwise`, `otherwise if`) | body | `done` |
230
+ | `for each <item> in <list>` | body | `done` |
231
+ | `for index <i> from <a> to <b>` | body | `done` |
232
+ | `while <cond>` | body | `done` |
233
+ | `repeat <n> times` / `repeat with <v> [...]` / `repeat while/until <cond>` | body | `done` |
234
+ | `make <name>(<params>)` (also `define <name>(<params>)`) | body | `done` |
235
+ | `intend <name>(<params>)` | body | `done` |
236
+ | `match <value> against` | `->` cases + `otherwise ->` | `done` |
237
+ | `switch <value> against` | `->` cases | `done` |
238
+ | `try` | body with `recover as <err>` / `finally` clauses | `done` |
239
+ | `web app` / `route <method> "<path>"` / `when someone visits "<path>"` / `listen on <port>` blocks | body | `done` |
240
+ | `database "file.db"` SQL blocks (`query`, `insert`, `update`, `delete`, `execute`) | raw SQL | `done` (or `end`) |
241
+ | `run in parallel` | concurrent statements (each statement's value is awaited and resolved with `Promise.all`, collected in body order) | `done as <name>` |
242
+ | `when "<event>" happens` | body | `done` |
243
+ | `every <interval>` / `schedule "<cron>"` | body | `done` |
244
+ | `websocket server`, `bot`, `whatsapp bot`, `mail transport` | body | `done` |
245
+ | `stream "<file>" as <line>` | body | `done` |
246
+ | `test "<name>"` | `check` / `equals` / `raises` | `done` |
247
+
248
+ A `make` body that contains `yield` compiles to a generator function
249
+ (`function*`). SQL block text is passed through verbatim to SQLite.
250
+
251
+ ## 6. Expressions
252
+
253
+ Recursive-descent parsing with precedence. Member access uses `of`:
254
+
255
+ ```plainscript
256
+ remember user as { profile: { name: "Ada" } }
257
+ show profile of user // user.profile
258
+ show name of profile of user // user.profile.name (chains build inside-out)
259
+ remember items as [10, 20, 30]
260
+ show items at position 1 // items[1]
261
+ show count of items // items.length
262
+ ```
263
+
264
+ Call syntax is plain `name(args)`. `to ... together` declares a function
265
+ (modern verb form of `make`/`define`); calling it is plain `add(a, b)` or
266
+ inline `a + b`.
267
+
268
+ Lambda functions: `(n) -> n * 2` (the arrow body is an expression — no
269
+ `give`/`return` inside it). The block-bodied form uses `do` and ends with
270
+ `done`: `(n) do ... done` with `give` inside. Lambdas can reference
271
+ surrounding variables.
272
+
273
+ ## 7. Built-in functions (STDLIB)
274
+
275
+ The runtime dispatches known call names at compile time; each is documented in
276
+ `compiler/generator.js` in the `STDLIB` table. Highlights:
277
+
278
+ - **I/O & console**: output statements `show` / `print` / `display` / `log`
279
+ (all compile to `console.log(...)`); input statements `ask "<prompt>" as
280
+ <name>` (`prompt` is a synonym). STDLIB functions: `stderr(...)`
281
+ (compiles to `console.error`), `confirm("prompt")` (yes/no prompt →
282
+ boolean), `choose("prompt", options)` (numbered picker → chosen option),
283
+ `clearTerminal()`, `terminalWidth()`, `terminalHeight()`
284
+ - **Math**: `abs`, `round`, `floor`, `ceil`, `sqrt`, `pow`, `min`, `max`,
285
+ `random`; `Math.*` member calls pass through to JavaScript. BigInt helpers:
286
+ `bigInt(n)`, `bigIntAsIntN(width, n)`, `bigIntAsUintN(width, n)`.
287
+ - **Statistics & vectors**: `mean`, `median`, `variance`, `deviation`,
288
+ `dotProduct`, `magnitude`, `normalize`
289
+ - **Randomness**: `randomInteger`, `randomChoice`, `shuffle`, `sample`,
290
+ `weightedChoice`
291
+ - **Strings**: `trim`, `substring`, `split`, `join`, `replace`,
292
+ `regexReplace`, `startsWith`, `endsWith`, `parseInt`, `parseFloat`,
293
+ `parseBoolean`, `characters`
294
+ - **Collections**: `first`, `last`, `push`, plus the functional statements
295
+ `gather each <item> in <list> giving <expr>` (maps the list),
296
+ `filter each <item> in <list> when <cond>` (filters the list),
297
+ `total each <item> in <list> giving <expr>` (sums into the variable) —
298
+ each statement reassigns its collection variable
299
+ - **Files**: `readFile`, `writeFile`, `appendFile`, `fileExists`, `copyFile`,
300
+ `moveFile`, `deleteFile`, `makeFolder`, `listFolder`
301
+ - **Network**: HTTP method expressions `get "url" timeout 5000`,
302
+ `post "url" with {...} headers {...}`; process and job helpers
303
+ `runCommand` (returns `{ ok, code, stdout, stderr }`), `sleep`,
304
+ `run background`, `run in parallel`
305
+ - **Data**: `jsonEncode`, `jsonDecode`, `yamlEncode`, `yamlDecode`,
306
+ `base64Encode`, `base64Decode`, `textToBytes`, `bytesToText`
307
+ - **Async**: `all of [...]`, `any of [...]`, `settled of [...]`
308
+ (combinator form — not `allOf`/`anyOf`/`settledOf`), `withTimeout(x, ms)`
309
+ - **AI**: `chat`, `chatWith`, `embedText`, `embedWith`, `similarity` — all
310
+ provider-based; no LLM is embedded in the runtime
311
+ - **Memoization**: `memoize(fn)` returns a cached wrapper
312
+ - **Regex matching**: `match pattern "..." in text as result`
313
+
314
+ ## 8. Assignment of grammar vs. prose
315
+
316
+ This reference is normative. Where a README, SPEC, or knowledge document
317
+ conflicts with the compiler, the compiler (and this file) win.
@@ -1,4 +1,4 @@
1
- # PlainScript 1.0.362 language specification
1
+ # PlainScript 1.0.363 language specification
2
2
 
3
3
  This reference covers the syntax implemented by `compiler/lexer.js` and
4
4
  `compiler/parser.js`. The runtime it generates lives in
@@ -9,7 +9,8 @@ repository's maintained example set.
9
9
 
10
10
  PlainScript is a line-oriented, intent-oriented language made for Node.js.
11
11
  Source files use `.pln`. Blocks end with `done` unless the syntax says
12
- `together`. Whitespace does not matter.
12
+ `together`, and `end` is accepted as a synonym for `done` in every block
13
+ position. Whitespace does not matter.
13
14
 
14
15
  The basic declaration forms are:
15
16
 
@@ -52,6 +53,47 @@ precedence. Word forms `plus`, `minus`, `times`, and `divided by` also work.
52
53
  `??` plus unary `-`, `wait for`, `typeof`, `void`, and `delete` are
53
54
  supported.
54
55
 
56
+ ### Assignment
57
+
58
+ `becomes` is the ordinary assignment operator. Compound forms combine an
59
+ operator with assignment; the symbols `+=`, `-=`, `*=`, `/=`, and `%=` (plus
60
+ the legacy `++=` spelling of `+=`) reuse the same grammar:
61
+
62
+ ```plainscript
63
+ remember score as 10
64
+ score += 5
65
+ score -= 3
66
+ score *= 2
67
+ score /= 4
68
+ score %= 7
69
+ let count be 0
70
+ count ++= 1
71
+ show score
72
+ ```
73
+
74
+ The word forms `or becomes`, `and becomes`, and `nullish becomes` map to
75
+ the logical assignments `||=`, `&&=`, and `??=`:
76
+
77
+ ```plainscript
78
+ let name be null
79
+ name or becomes "Grace"
80
+ name and becomes name
81
+ name nullish becomes "default"
82
+ show name
83
+ ```
84
+
85
+ `set <expr> to <value>` and `change <expr> to <value>` are prefix synonyms
86
+ for `becomes`, and the same words work postfixed after the expression:
87
+
88
+ ```plainscript
89
+ let age be 16
90
+ set age to 17
91
+ change age to 18
92
+ age set to 19
93
+ age change to 20
94
+ show age
95
+ ```
96
+
55
97
  ## Conditions
56
98
 
57
99
  ```plainscript
@@ -71,7 +113,7 @@ Operators:
71
113
  | `more than`, `is greater than`, `is above` | `>` |
72
114
  | `fewer than`, `is less than`, `is below` | `<` |
73
115
  | `is at least` | `>=` |
74
- | `is most` | `<=` |
116
+ | `is at most` | `<=` |
75
117
  | `contains`, `starts with`, `ends with`, `made of` | string predicates |
76
118
  | `between low and high` | inclusive range |
77
119
  | `has field field` | property existence |
@@ -92,6 +134,26 @@ done
92
134
  show add(2, 3)
93
135
  ```
94
136
 
137
+ Functions and intents may declare a return contract with `returns` (or the
138
+ equivalent `returning`) after the parameter list. The static checker validates
139
+ each `give`/`return` value and reports a missing return when a declared
140
+ function has no return value:
141
+
142
+ ```plainscript
143
+ make add(a as number, b as number) returns number
144
+ give a + b
145
+ done
146
+
147
+ intend greeting(name as text) returns text
148
+ give `Hello, ${name}`
149
+ done
150
+ ```
151
+
152
+ Return contracts use the same primitive, optional, list, dictionary, union, and
153
+ declared-record types as parameter contracts. Untyped functions remain valid,
154
+ and a function call with a return contract contributes that type to subsequent
155
+ static checking.
156
+
95
157
  Function parameters can have simple defaults:
96
158
 
97
159
  ```plainscript
@@ -112,6 +174,76 @@ done
112
174
  `yield` turns a function into a generator. Functions can use `wait for` and
113
175
  other async operations.
114
176
 
177
+ `intend name(params)` is a callable declaration equivalent to `make` at
178
+ runtime, but it remains an `IntentDeclaration` in the AST and compiler IR. This
179
+ metadata is reserved for future contract analysis, documentation generation,
180
+ and semantic diagnostics.
181
+
182
+ ```plainscript
183
+ intend greet(name)
184
+ give `Hello ${name}`
185
+ done
186
+ ```
187
+
188
+ Tooling can inspect the backend-neutral representation with:
189
+
190
+ ```bash
191
+ plainscript ir path/to/program.pln
192
+ ```
193
+
194
+ The command emits versioned JSON and preserves statement kinds, source spans,
195
+ function parameters, and intent metadata. The JavaScript backend continues to
196
+ consume the existing AST while alternate backends are developed against this
197
+ stable boundary.
198
+
199
+ ## Typed data contracts
200
+
201
+ Contextual `type` declarations describe the required shape of a record. A
202
+ function parameter can refer to a declared type after `as`; unlike a default
203
+ literal such as `name as "friend"`, a type name is an identifier such as
204
+ `User`.
205
+
206
+ ```plainscript
207
+ type User
208
+ id is number
209
+ name is text
210
+ active is optional boolean
211
+ tags is list of text
212
+ metadata is dictionary of text
213
+ done
214
+
215
+ make greet(user as User)
216
+ give `Hello, ${user.name}`
217
+ done
218
+ ```
219
+
220
+ The current implementation emits the contract into the generated program and
221
+ validates typed arguments at function entry. Required fields must be present;
222
+ primitive values must match their declared type. `optional T` accepts a missing
223
+ or null value, while `T or null` accepts null in addition to `T`. A declared
224
+ contract can also be used inside `list of` and `dictionary of`. The static
225
+ checker consumes the same AST and IR and reports unknown contract names, arity
226
+ errors, invalid literal fields, missing required fields, and invalid member
227
+ access. Generic types, whole-program inference, and compile-time exhaustiveness
228
+ checking are not yet part of this slice.
229
+
230
+ The checker powers the stdio language server started with `plainscript-lsp`.
231
+ The server publishes these diagnostics and provides hover, completion,
232
+ definition, and document-symbol responses using standard LSP JSON-RPC framing.
233
+
234
+ Mutable bindings can declare recursive collection contracts with `as` before
235
+ the initializer:
236
+
237
+ ```text
238
+ let users as list of User is [{ id: 1, name: "Ada" }]
239
+ let usersById as dictionary of User is { first: { id: 1, name: "Ada" } }
240
+ ```
241
+
242
+ The checker validates every list element and dictionary value, including nested
243
+ record fields. Optional and union element types use the same rules as function
244
+ contracts. A known `list of T` or `dictionary of T` contributes `T` to indexed
245
+ access, and null checks narrow optional values within the checked branch.
246
+
115
247
  ## Control flow
116
248
 
117
249
  ```plainscript
@@ -132,6 +264,33 @@ Use `break` and `continue` inside loops. `match value against` uses `->`
132
264
  case arrows and `otherwise`. `switch value against` works the same way and
133
265
  is just another way to write it.
134
266
 
267
+ Regex capture uses `match pattern "..." in text as result`:
268
+ ```plainscript
269
+ match pattern "^(\\d+)$" in "4061" as digits
270
+ show digits // → "4061"
271
+ ```
272
+
273
+ Collection size uses `count of`:
274
+ ```plainscript
275
+ show count of [1, 2, 3] // → 3
276
+ show count of "hello" // → 5
277
+ ```
278
+
279
+ `run in parallel ... done as <name>` executes each statement in the block as
280
+ its own concurrent async job and awaits them together with `Promise.all`,
281
+ collecting each statement's value in body order. It is not a worker-thread
282
+ API:
283
+
284
+ ```plainscript
285
+ run in parallel
286
+ makeJob(1)
287
+ makeJob(2)
288
+ done as results
289
+ ```
290
+
291
+ An expression statement (typically a call) contributes its return value; any
292
+ other statement runs as its own async job and contributes `undefined`.
293
+
135
294
  ## Record kinds
136
295
 
137
296
  ```plainscript
@@ -237,10 +396,106 @@ retry 3 times every 1 second
237
396
  done
238
397
  ```
239
398
 
240
- Concurrency helpers are `allOf`, `anyOf`, `settledOf`, and `withTimeout`.
399
+ Concurrency helpers are `all of`, `any of`, `settled of`, and `withTimeout`.
241
400
  Recurring blocks use `every 5 minutes ... done` and
242
401
  `schedule "0 * * * *" ... done`.
243
402
 
403
+ ## Interactive terminal
404
+
405
+ Simple CLI prompts read from stdin and write to stdout. `confirm("question")`
406
+ asks a yes/no question and resolves to a boolean; `choose("question",
407
+ options)` prints a numbered menu and resolves to the picked option (or `null`
408
+ when cancelled):
409
+
410
+ ```plainscript
411
+ remember ok as confirm("Delete this file?")
412
+ remember color as choose("Pick a color", ["red", "green", "blue"])
413
+ show color
414
+ ```
415
+
416
+ `clearTerminal()` clears the screen, `terminalWidth()` and
417
+ `terminalHeight()` report the terminal size, and `stderr(...)` writes to
418
+ standard error so diagnostics never pollute stdout:
419
+
420
+ ```plainscript
421
+ stderr("starting")
422
+ clearTerminal()
423
+ show "width " + terminalWidth() + " height " + terminalHeight()
424
+ stderr("done")
425
+ ```
426
+
427
+ ## Statistics, vectors, and randomness
428
+
429
+ Numeric statistics over an array:
430
+
431
+ | Function | Result |
432
+ | --- | --- |
433
+ | `mean(values)` | Arithmetic mean, or `NaN` for an empty array. |
434
+ | `median(values)` | Middle value; average of the two middle values for even-length arrays. |
435
+ | `variance(values)` | Sample variance (`n - 1` denominator). |
436
+ | `deviation(values)` | Sample standard deviation. |
437
+
438
+ ```plainscript
439
+ remember data as [2, 4, 4, 4, 5, 5, 7, 9]
440
+ show mean(data)
441
+ show median(data)
442
+ show variance(data)
443
+ show deviation(data)
444
+ ```
445
+
446
+ Vector primitives operate on numeric arrays:
447
+
448
+ ```plainscript
449
+ remember a as [1, 2, 3]
450
+ remember b as [4, 5, 6]
451
+ show dotProduct(a, b)
452
+ show magnitude(a)
453
+ show normalize(a)
454
+ ```
455
+
456
+ `dotProduct(a, b)` sums the element-wise products, `magnitude(v)` is the
457
+ Euclidean length, and `normalize(v)` is the unit vector (a zero vector maps
458
+ to the same-length zero vector).
459
+
460
+ Randomness helpers (all inclusive where a range applies):
461
+
462
+ ```plainscript
463
+ remember die as randomInteger(1, 6)
464
+ remember coin as randomChoice(["heads", "tails"])
465
+ remember loot as weightedChoice(["common", "rare", "legendary"], [0.7, 0.25, 0.05])
466
+ remember deck as shuffle(["A", "2", "3", "4", "5"])
467
+ remember hand as sample([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], 3)
468
+ ```
469
+
470
+ `randomInteger(low, high)` is inclusive on both ends, `randomChoice(items)`
471
+ picks one element, `weightedChoice(items, weights)` picks an element weighted
472
+ by its parallel weight, `shuffle(items)` returns a new shuffled copy, and
473
+ `sample(items, n)` returns a shuffled copy cut to `n` elements.
474
+
475
+ ## Memoization and helpers
476
+
477
+ `memoize(function)` wraps a callable so repeated calls with the same argument
478
+ list hit a cache instead of re-running:
479
+
480
+ ```plainscript
481
+ make slowSquare(n)
482
+ give n * n
483
+ done
484
+
485
+ remember fastSquare as memoize(slowSquare)
486
+ show fastSquare(9)
487
+ ```
488
+
489
+ `parseBoolean(text)` treats `"true"`, `"yes"`, `"1"`, and `"on"` (ignoring
490
+ case and surrounding whitespace) as `true` and everything else as `false`.
491
+ `characters(text)` splits a string into an array of its characters:
492
+
493
+ ```plainscript
494
+ remember enabled as parseBoolean("yes")
495
+ remember letters as characters("hello")
496
+ show count of letters
497
+ ```
498
+
244
499
  ## AI providers
245
500
 
246
501
  `chat(model, messages, options)` and `embedText(model, text, options)` talk
@@ -532,6 +787,10 @@ remember engine as matter.Engine.create()
532
787
  remember scene as new THREE.Scene()
533
788
  ```
534
789
 
790
+ > Removed: a `javascript ... done` raw block existed briefly in 1.0.363 but
791
+ > is no longer part of the language. Interop is through imports (`use` /
792
+ > `bring`) and normal member calls, which are always available.
793
+
535
794
  Call anything - member chains need no special syntax, and there is no wrapper
536
795
  around values:
537
796
 
@@ -596,4 +855,4 @@ plainscript version
596
855
  ```
597
856
 
598
857
  `check` parses imports, generates JavaScript, and validates that output with
599
- Node's parser without writing files.
858
+ Node's parser without writing files.