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.
- package/README.md +394 -54
- package/compiler/bundler.js +78 -3
- package/compiler/cli.js +239 -30
- package/compiler/formatter.js +21 -1
- package/compiler/generator.js +453 -107
- package/compiler/ir.js +62 -0
- package/compiler/lexer.js +42 -7
- package/compiler/lsp.js +290 -0
- package/compiler/parser.js +820 -113
- package/compiler/type-checker.js +440 -0
- package/compiler/version.js +1 -1
- package/docs/CAPABILITY_GAP_AUDIT.md +19 -3
- package/docs/GAME-PROMPT.md +3 -3
- package/docs/PLAINSCRIPT-GRAMMAR.md +317 -0
- package/docs/PLAINSCRIPT-SPEC.md +264 -5
- package/docs/V1.1-TYPED-COLLECTIONS-DESIGN.md +220 -0
- package/docs/index.html +5 -5
- package/docs/website/script.js +1 -1
- package/examples/ai-memory-cli.pln +221 -0
- package/examples/ai-memory.json +1 -0
- package/examples/ai-providers.pln +1 -1
- package/examples/arrays.pln +1 -1
- package/examples/async-errors.pln +1 -1
- package/examples/auth-api.pln +1 -1
- package/examples/auth-sessions.pln +1 -1
- package/examples/basics.pln +1 -1
- package/examples/bots.pln +1 -1
- package/examples/browser-interactive/README.md +1 -1
- package/examples/browser-interactive/src/interactive.pln +1 -1
- package/examples/cache-and-jobs.pln +1 -1
- package/examples/cache-schedule.pln +1 -1
- package/examples/canvas-game/README.md +1 -1
- package/examples/canvas-game/src/game.pln +1 -1
- package/examples/collections.pln +1 -1
- package/examples/compound-assignments.pln +24 -0
- package/examples/concurrency.pln +2 -2
- package/examples/conditions.pln +1 -1
- package/examples/database.pln +1 -1
- package/examples/day2.pln +1 -1
- package/examples/day3.pln +1 -1
- package/examples/deployment.pln +1 -1
- package/examples/email-send.pln +1 -1
- package/examples/error-handling.pln +1 -1
- package/examples/expressions.pln +1 -1
- package/examples/file-manager-cli.pln +51 -0
- package/examples/file-uploads.pln +1 -1
- package/examples/files-and-config.pln +1 -1
- package/examples/files.pln +1 -1
- package/examples/football-backend/app.pln +1 -1
- package/examples/functions.pln +1 -1
- package/examples/hello.pln +1 -1
- package/examples/http-client.pln +1 -1
- package/examples/http.pln +1 -1
- package/examples/id-verification/app.pln +1 -1
- package/examples/interactive-cli.pln +34 -0
- package/examples/javascript-library/README.md +1 -1
- package/examples/javascript-library/src/interop.pln +1 -1
- package/examples/json.pln +1 -1
- package/examples/loops.pln +1 -1
- package/examples/memoize-demo.pln +31 -0
- package/examples/modules/app.pln +1 -1
- package/examples/modules/main.pln +1 -1
- package/examples/modules/math.pln +1 -1
- package/examples/mongo.pln +1 -1
- package/examples/normalization-forms.pln +22 -0
- package/examples/objects.pln +1 -1
- package/examples/ocr.pln +1 -1
- package/examples/packages.pln +1 -1
- package/examples/random-cli.pln +32 -0
- package/examples/record-kinds.pln +1 -1
- package/examples/records.pln +1 -1
- package/examples/rest-api-fetch.pln +1 -1
- package/examples/rest-api.pln +1 -1
- package/examples/run-in-parallel.pln +25 -0
- package/examples/scheduled-tasks.pln +1 -1
- package/examples/search-and-filter.pln +1 -1
- package/examples/server.pln +1 -1
- package/examples/sessions-and-cookies.pln +1 -1
- package/examples/sqlite.pln +1 -1
- package/examples/start.pln +1 -1
- package/examples/stats-cli.pln +29 -0
- package/examples/stdlib.pln +1 -1
- package/examples/string-helpers.pln +23 -0
- package/examples/string-verbs.pln +1 -1
- package/examples/telegram-ai-bot.pln +1 -1
- package/examples/telegram-bot.pln +1 -1
- package/examples/terminal-cli.pln +11 -0
- package/examples/testing.pln +1 -1
- package/examples/three-dimensional/README.md +1 -1
- package/examples/three-dimensional/src/scene.pln +1 -1
- package/examples/todo-cli.pln +98 -0
- package/examples/typed-collections.pln +21 -0
- package/examples/web-api.pln +1 -1
- package/examples/web-app.pln +1 -1
- package/examples/websocket-server.pln +1 -1
- package/examples/websocket.pln +1 -1
- package/examples/whatsapp-bot/pairing.pln +1 -1
- package/examples/whatsapp-bot/qr.pln +1 -1
- 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.
|
package/docs/PLAINSCRIPT-SPEC.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# PlainScript 1.0.
|
|
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
|
|
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 `
|
|
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.
|