plainscript-lang 1.0.36 → 1.0.362
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 +252 -20
- package/compiler/bundler.js +4 -4
- package/compiler/cli.js +18 -18
- package/compiler/dependency-detector.js +34 -22
- package/compiler/generator.js +326 -196
- package/compiler/lexer.js +49 -39
- package/compiler/parser.js +552 -181
- package/compiler/sourcemap.js +1 -1
- package/compiler/version.js +1 -1
- package/docs/CAPABILITY_GAP_AUDIT.md +2 -2
- package/docs/FB-PROMPT.md +524 -0
- package/docs/GAME-PROMPT.md +56 -55
- package/docs/PLAINSCRIPT-SPEC.md +16 -15
- package/docs/index.html +13 -6
- package/docs/website/script.js +1 -1
- package/docs/website/style.css +3 -3
- package/examples/ai-providers.pln +1 -1
- package/examples/arrays.pln +1 -1
- package/examples/async-errors.pln +2 -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 +3 -3
- 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 +4 -4
- package/examples/canvas-game/src/game.pln +1 -1
- package/examples/collections.pln +1 -1
- package/examples/concurrency.pln +1 -1
- 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 +3 -2
- package/examples/expressions.pln +1 -1
- 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/javascript-library/README.md +6 -6
- package/examples/javascript-library/public/index.html +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/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/objects.pln +1 -1
- package/examples/ocr.pln +1 -1
- package/examples/packages.pln +1 -1
- 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/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/stdlib.pln +1 -1
- package/examples/string-verbs.pln +1 -1
- package/examples/telegram-ai-bot.pln +1 -1
- package/examples/telegram-bot.pln +1 -1
- package/examples/testing.pln +1 -1
- package/examples/three-dimensional/README.md +2 -2
- package/examples/three-dimensional/src/scene.pln +1 -1
- 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 +2 -2
- package/examples/whatsapp-bot/qr.pln +2 -2
- package/package.json +11 -12
package/README.md
CHANGED
|
@@ -32,11 +32,15 @@ Describe *what* you want. The compiler decides *how* to implement it in JavaScri
|
|
|
32
32
|
- [Variables](#variables)
|
|
33
33
|
- [String Templates](#string-templates)
|
|
34
34
|
- [Conditions](#conditions)
|
|
35
|
+
- [Conditional expressions](#conditional-expressions)
|
|
35
36
|
- [Functions](#functions)
|
|
37
|
+
- [Lambdas](#lambdas)
|
|
36
38
|
- [Arrays & Objects](#arrays--objects)
|
|
39
|
+
- [Dictionaries, Sets & Tuples](#dictionaries-sets--tuples)
|
|
37
40
|
- [Loops](#loops)
|
|
38
41
|
- [Natural-Language Expressions](#natural-language-expressions)
|
|
39
42
|
- [Logical Assignment](#logical-assignment)
|
|
43
|
+
- [Error handling, async, and events](#error-handling-async-and-events)
|
|
40
44
|
- [Record Kinds, Concurrency & More](#record-kinds-concurrency--more)
|
|
41
45
|
- [Backend Services](#backend-services)
|
|
42
46
|
- [Databases](#databases)
|
|
@@ -72,7 +76,7 @@ Describe *what* you want. The compiler decides *how* to implement it in JavaScri
|
|
|
72
76
|
|
|
73
77
|
## Why PlainScript
|
|
74
78
|
|
|
75
|
-
Most languages ask you to describe *how* a computation happens: loop constructs, control flow, boilerplate. PlainScript inverts that. You write source that reads like an instruction to a competent engineer, and a deterministic compiler
|
|
79
|
+
Most languages ask you to describe *how* a computation happens: loop constructs, control flow, boilerplate. PlainScript inverts that. You write source that reads like an instruction to a competent engineer, and a deterministic compiler - no rules engine, no AI, no hidden codegen - turns it into JavaScript.
|
|
76
80
|
|
|
77
81
|
| | |
|
|
78
82
|
|---|---|
|
|
@@ -118,7 +122,7 @@ done
|
|
|
118
122
|
</tr>
|
|
119
123
|
</table>
|
|
120
124
|
|
|
121
|
-
**Current version:** `v1.0.
|
|
125
|
+
**Current version:** `v1.0.362` - the `plainscript-lang` npm package, with a TypeScript-style production build (`plainscript build` → `dist/`, source names and structure preserved).
|
|
122
126
|
|
|
123
127
|
---
|
|
124
128
|
|
|
@@ -127,7 +131,7 @@ done
|
|
|
127
131
|
```bash
|
|
128
132
|
npx plainscript new myapp # scaffolds src/app.pln and package.json
|
|
129
133
|
cd myapp
|
|
130
|
-
npm install # installs
|
|
134
|
+
npm install # installs the compiler and runtime packages
|
|
131
135
|
npm run build # compiles src/ -> dist/ (plainscript build)
|
|
132
136
|
node dist/app.js # or: npm start
|
|
133
137
|
```
|
|
@@ -136,18 +140,53 @@ Adding PlainScript to an existing project:
|
|
|
136
140
|
|
|
137
141
|
```bash
|
|
138
142
|
npm install --save-dev plainscript-lang
|
|
139
|
-
# start writing src/*.pln files
|
|
143
|
+
# start writing src/*.pln files - plainscript build auto-discovers them
|
|
140
144
|
```
|
|
141
145
|
|
|
142
146
|
No global install is required. Everything runs through `npm` scripts and `npx`.
|
|
143
147
|
|
|
148
|
+
### Supported Node.js and dependency policy
|
|
149
|
+
|
|
150
|
+
The compiler and its checked-in dependency tree support **Node.js 18 or newer**.
|
|
151
|
+
Use the lockfile for reproducible installs:
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
npm ci
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
The compiler package intentionally does not install the optional WhatsApp
|
|
158
|
+
adapter. This keeps a normal `npm ci` independent of Baileys' native/GitHub
|
|
159
|
+
transitives and lets projects that do not use WhatsApp install cleanly on the
|
|
160
|
+
Node 18 floor. The SQLite, MongoDB, and Redis versions in `package.json` are
|
|
161
|
+
the last compatible major lines for that floor.
|
|
162
|
+
|
|
163
|
+
WhatsApp projects have a separate adapter requirement. `plainscript install`
|
|
164
|
+
uses the pinned default `@whiskeysockets/baileys@6.7.24` (Node.js 20 or newer)
|
|
165
|
+
and `qrcode-terminal`. If a package firewall or registry cannot provide that
|
|
166
|
+
adapter, install a Baileys-compatible package or local fork yourself and select
|
|
167
|
+
it in the bot block:
|
|
168
|
+
|
|
169
|
+
```plainscript
|
|
170
|
+
whatsapp bot
|
|
171
|
+
use baileys "./vendor/baileys"
|
|
172
|
+
auth "session"
|
|
173
|
+
login qr
|
|
174
|
+
done
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
For a local adapter, install it from the project directory (for example,
|
|
178
|
+
`npm install ./vendor/baileys`) and ensure it exposes the Baileys default
|
|
179
|
+
socket export plus `useMultiFileAuthState`, `makeCacheableSignalKeyStore`, and
|
|
180
|
+
`DisconnectReason`. Local adapter paths are not passed to `npm install` by
|
|
181
|
+
`plainscript install`.
|
|
182
|
+
|
|
144
183
|
---
|
|
145
184
|
|
|
146
185
|
## CLI Reference
|
|
147
186
|
|
|
148
187
|
| Command | Description |
|
|
149
188
|
|---|---|
|
|
150
|
-
| `plainscript run <file.pln>` | Installs missing dependencies, compiles, and executes. Runs from a scratch directory
|
|
189
|
+
| `plainscript run <file.pln>` | Installs missing dependencies, compiles, and executes. Runs from a scratch directory - nothing is written into your project. |
|
|
151
190
|
| `plainscript build [file.pln]` | Compiles to `dist/`. With no argument, builds every `.pln` file under the source root, preserving names and folder structure. |
|
|
152
191
|
| `plainscript check <file.pln>` | Checks syntax only. No output, no execution. |
|
|
153
192
|
| `plainscript fmt <file.pln>` | Formats a PlainScript file in place. |
|
|
@@ -165,7 +204,7 @@ No global install is required. Everything runs through `npm` scripts and `npx`.
|
|
|
165
204
|
|
|
166
205
|
## Building & Configuration
|
|
167
206
|
|
|
168
|
-
`plainscript build` is a deterministic production build
|
|
207
|
+
`plainscript build` is a deterministic production build - TypeScript-style, but for `.pln` sources - with zero configuration required.
|
|
169
208
|
|
|
170
209
|
- Run with no argument and it discovers every `.pln` file under `src/`, compiling each to `dist/` while **preserving source file names and folder structure**: `src/messi.pln` → `dist/messi.js`, `src/helpers/math.pln` → `dist/helpers/math.js`.
|
|
171
210
|
- `plainscript build <file.pln>` compiles a single file into `dist/`.
|
|
@@ -198,16 +237,23 @@ For projects that need custom output or source directories, add a `plainscript.c
|
|
|
198
237
|
"build": "plainscript build",
|
|
199
238
|
"prepare": "plainscript build"
|
|
200
239
|
},
|
|
201
|
-
"devDependencies": { "plainscript-lang": "^1.0.
|
|
240
|
+
"devDependencies": { "plainscript-lang": "^1.0.362" }
|
|
202
241
|
}
|
|
203
242
|
```
|
|
204
243
|
|
|
205
|
-
`src/index.pln` builds to `dist/index.js`; consumers install and `require()` it like any Node package. There is no PlainScript-specific registry or format
|
|
244
|
+
`src/index.pln` builds to `dist/index.js`; consumers install and `require()` it like any Node package. There is no PlainScript-specific registry or format - standard `package.json` semantics apply.
|
|
206
245
|
|
|
207
246
|
---
|
|
208
247
|
|
|
209
248
|
## Language Tour
|
|
210
249
|
|
|
250
|
+
PlainScript is a fixed vocabulary of English verbs compiled to JavaScript. Every
|
|
251
|
+
construct follows the same rhythm: a word opens a block, `done` closes it, and
|
|
252
|
+
`give` returns a value - a sentence you could say to a colleague ("if the score
|
|
253
|
+
is at least 80, show accepted, otherwise review") is valid source. The sections
|
|
254
|
+
below keep the code first, with a short note on what each construct is *for* and
|
|
255
|
+
the constraint that matters when you use it.
|
|
256
|
+
|
|
211
257
|
### Variables
|
|
212
258
|
|
|
213
259
|
```
|
|
@@ -216,6 +262,12 @@ let age be 16
|
|
|
216
262
|
set age to 17
|
|
217
263
|
```
|
|
218
264
|
|
|
265
|
+
`remember name as "Ada"` and `let name be "Ada"` are two spellings of the same
|
|
266
|
+
declaration; `set name to ...`, `name becomes ...`, and `name is now ...` all
|
|
267
|
+
reassign it. Numbers, strings, and booleans behave like JavaScript primitives;
|
|
268
|
+
lists, records, dictionaries, and sets are *references*, so pointing two names
|
|
269
|
+
at the same list means they see the same data.
|
|
270
|
+
|
|
219
271
|
### String Templates
|
|
220
272
|
|
|
221
273
|
Backtick-delimited strings preserve whitespace and support `${expression}` interpolation:
|
|
@@ -233,10 +285,17 @@ Best regards,
|
|
|
233
285
|
The Team`
|
|
234
286
|
```
|
|
235
287
|
|
|
236
|
-
Interpolation compiles directly to JavaScript template literals
|
|
288
|
+
Interpolation compiles directly to JavaScript template literals - it is not evaluated at compile time. Literal dollar signs without `{` are preserved as-is.
|
|
237
289
|
|
|
238
290
|
### Conditions
|
|
239
291
|
|
|
292
|
+
`if <condition> ... done` runs its block when the condition is true, and the
|
|
293
|
+
optional `otherwise` block runs when it is false (`when ... done` is the same
|
|
294
|
+
statement used in web and event contexts). Conditions read like English, and a
|
|
295
|
+
comparison is itself a value: `score is at least 80` is `true` or `false`, so it
|
|
296
|
+
can be stored, printed, passed to a function, or joined with `and` / `or` /
|
|
297
|
+
`not`. When you need a *value* rather than a block, use `choosing` (below).
|
|
298
|
+
|
|
240
299
|
```
|
|
241
300
|
when age is at least 18
|
|
242
301
|
show "Adult"
|
|
@@ -277,6 +336,19 @@ All comparison operators:
|
|
|
277
336
|
| `has field "x"` | `"x" in obj` |
|
|
278
337
|
| `at position key` | `obj[key]` |
|
|
279
338
|
|
|
339
|
+
### Conditional expressions
|
|
340
|
+
|
|
341
|
+
`choosing` is the value form of `if`: pick between two expressions and keep the
|
|
342
|
+
whole thing inline - in an argument, a `give`, or a list element.
|
|
343
|
+
|
|
344
|
+
```
|
|
345
|
+
remember verdict as choosing score is at least 90 then "A" otherwise "B"
|
|
346
|
+
show choosing score is below 60 then "low" otherwise "ok"
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
`choosing <condition> then <a> otherwise <b>` evaluates to `<a>` when the
|
|
350
|
+
condition is true and `<b>` otherwise.
|
|
351
|
+
|
|
280
352
|
### Functions
|
|
281
353
|
|
|
282
354
|
```
|
|
@@ -290,8 +362,46 @@ to multiply x and y together
|
|
|
290
362
|
done
|
|
291
363
|
```
|
|
292
364
|
|
|
365
|
+
`make name(args)` and its `to ... together` spelling define a function; `done`
|
|
366
|
+
closes it - the PlainScript form of JavaScript's `function`. `give <value>` (or
|
|
367
|
+
`give back <value>`) returns; `give` alone simply ends the function. A `make`
|
|
368
|
+
function is a value like any other, so it can be stored with `remember`, passed
|
|
369
|
+
as an argument, or returned from another function. Arguments are optional with
|
|
370
|
+
defaults: `make label(name as "guest")`.
|
|
371
|
+
|
|
372
|
+
### Lambdas
|
|
373
|
+
|
|
374
|
+
A lambda is a function without a name, written where a value is expected -
|
|
375
|
+
`(a, b) -> a + b` is JavaScript's `(a, b) => a + b`. Use the arrow form for a
|
|
376
|
+
one-expression body and the `do ... done` form when the body has several
|
|
377
|
+
statements:
|
|
378
|
+
|
|
379
|
+
```
|
|
380
|
+
remember add as (a, b) -> a + b
|
|
381
|
+
show add(2, 3)
|
|
382
|
+
|
|
383
|
+
remember grade as (score) do
|
|
384
|
+
if score is at least 90
|
|
385
|
+
give "excellent"
|
|
386
|
+
otherwise
|
|
387
|
+
give "keep practicing"
|
|
388
|
+
done
|
|
389
|
+
done
|
|
390
|
+
|
|
391
|
+
remember doubled as numbers.map((n) -> n * 2)
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
Lambdas are ordinary values: store them, put them in lists and records, pass
|
|
395
|
+
them to `.map` / `.filter` / `.find` / `.forEach`, and return or chain them
|
|
396
|
+
(`mul(2)(3)(5)`) to build factories and curried helpers.
|
|
397
|
+
|
|
293
398
|
### Arrays & Objects
|
|
294
399
|
|
|
400
|
+
`list with ...` is PlainScript's spelling of an array; `record with ... done`
|
|
401
|
+
is a plain object. Both are ordinary values, so lists hold records, records
|
|
402
|
+
hold lists, and lambdas can live anywhere a value can. Read and write them with
|
|
403
|
+
`.name`, `[index]`, or the natural-language forms later in this tour.
|
|
404
|
+
|
|
295
405
|
```
|
|
296
406
|
let players be list with "Haaland", "Foden", "Rodri"
|
|
297
407
|
show players[0]
|
|
@@ -304,8 +414,47 @@ done
|
|
|
304
414
|
show user.name
|
|
305
415
|
```
|
|
306
416
|
|
|
417
|
+
### Dictionaries, Sets & Tuples
|
|
418
|
+
|
|
419
|
+
JavaScript's `Map` and `Set` have direct spellings, and tuples are fixed-size
|
|
420
|
+
arrays you usually unpack all at once:
|
|
421
|
+
|
|
422
|
+
```
|
|
423
|
+
remember lookup as dictionary with "alpha" is 1 and "beta" is 2 done
|
|
424
|
+
show lookup.get("beta") // 2
|
|
425
|
+
|
|
426
|
+
remember tags as set with "admin", "editor", "admin" done // duplicates collapse
|
|
427
|
+
|
|
428
|
+
remember point as tuple with 10, 20 and 30 done
|
|
429
|
+
unpack point into x, y and z // x=10, y=20, z=30
|
|
430
|
+
show x + y + z
|
|
431
|
+
```
|
|
432
|
+
|
|
433
|
+
Dictionary and set entries are joined with `and`; a tuple separates its members
|
|
434
|
+
with commas and `and` before the final member. `show <value>` accepts any value,
|
|
435
|
+
and JSON data arrives as nested lists and records.
|
|
436
|
+
|
|
307
437
|
### Loops
|
|
308
438
|
|
|
439
|
+
`for each item in <collection> ... done` visits every element, and `while
|
|
440
|
+
<condition> ... done` repeats until the condition is false. Counted loops come
|
|
441
|
+
in sentence form too:
|
|
442
|
+
|
|
443
|
+
```
|
|
444
|
+
repeat 5 times
|
|
445
|
+
show "tick"
|
|
446
|
+
done
|
|
447
|
+
|
|
448
|
+
remember energy as 9
|
|
449
|
+
repeat while energy is above 0
|
|
450
|
+
energy becomes energy - 1
|
|
451
|
+
done
|
|
452
|
+
```
|
|
453
|
+
|
|
454
|
+
`for every item in basket` is an alias for `for each`, `repeat until <condition>`
|
|
455
|
+
flips the `while` sense, and `for index i from 0 to 9` gives a zero-based
|
|
456
|
+
counter when you need positions.
|
|
457
|
+
|
|
309
458
|
```
|
|
310
459
|
for each player in players
|
|
311
460
|
show player
|
|
@@ -335,7 +484,7 @@ show player two from players // players[1]
|
|
|
335
484
|
first player from players is now "Haaland" // players[0] = "Haaland"
|
|
336
485
|
```
|
|
337
486
|
|
|
338
|
-
Number words from `one` to `twenty` map to one-based positions
|
|
487
|
+
Number words from `one` to `twenty` map to one-based positions - `player one` is the first item.
|
|
339
488
|
|
|
340
489
|
**Collections**
|
|
341
490
|
|
|
@@ -370,6 +519,10 @@ The older `readFile()` / `writeFile()` forms still work and are unchanged.
|
|
|
370
519
|
|
|
371
520
|
### Logical Assignment
|
|
372
521
|
|
|
522
|
+
The word-style assignment operators keep the common "fill the empty value"
|
|
523
|
+
pattern on one line - PlainScript for `flag = flag || true` and
|
|
524
|
+
`val = val ?? "default"`:
|
|
525
|
+
|
|
373
526
|
```
|
|
374
527
|
let flag be false
|
|
375
528
|
flag or is now true
|
|
@@ -380,8 +533,53 @@ val nullish is now "default"
|
|
|
380
533
|
show val
|
|
381
534
|
```
|
|
382
535
|
|
|
536
|
+
### Error handling, async, and events
|
|
537
|
+
|
|
538
|
+
Programs that fail should say so. `raise <value>` throws an error, `try` /
|
|
539
|
+
`recover as err` / `finally` catch it, and `retry N times every Mms` re-runs a
|
|
540
|
+
block that may fail transiently:
|
|
541
|
+
|
|
542
|
+
```
|
|
543
|
+
raise "not implemented"
|
|
544
|
+
|
|
545
|
+
try
|
|
546
|
+
remember data as jsonDecode(raw)
|
|
547
|
+
recover as err
|
|
548
|
+
show "bad json: " + message of err
|
|
549
|
+
finally
|
|
550
|
+
show "request complete"
|
|
551
|
+
done
|
|
552
|
+
|
|
553
|
+
retry 3 times every 2 seconds
|
|
554
|
+
show "fetching..."
|
|
555
|
+
done
|
|
556
|
+
```
|
|
557
|
+
|
|
558
|
+
Asynchronous work uses `wait for <promise>` (or `await <promise>`). A `make`
|
|
559
|
+
function or lambda that `wait for`s a promise becomes async automatically, and
|
|
560
|
+
`all of [...]`, `any of [...]`, and `settled of [...]` run several promises at
|
|
561
|
+
once. Events bind with `when <target> "<event>" happens [as <name>] ... done` -
|
|
562
|
+
the DOM equivalent of `addEventListener` - and server/websocket forms follow
|
|
563
|
+
the same `when ... done` pattern.
|
|
564
|
+
|
|
383
565
|
### Record Kinds, Concurrency & More
|
|
384
566
|
|
|
567
|
+
For the shapes that repeat in a program - a user, a message, an order - declare
|
|
568
|
+
a **record kind** and construct instances with `create`. Kinds behave like
|
|
569
|
+
plain objects with a known field list: setting an unknown field throws, which
|
|
570
|
+
catches typos early.
|
|
571
|
+
|
|
572
|
+
```
|
|
573
|
+
define a kind called "Player" with
|
|
574
|
+
name is ""
|
|
575
|
+
goals is 0
|
|
576
|
+
done
|
|
577
|
+
|
|
578
|
+
remember player as create a Player with name "Ada" and goals 4
|
|
579
|
+
player.goals becomes player.goals + 1
|
|
580
|
+
show player.goals
|
|
581
|
+
```
|
|
582
|
+
|
|
385
583
|
PlainScript 1.0.2 closes most of the gap with TypeScript-class languages using its own grammar. The full audit lives in [`docs/CAPABILITY_GAP_AUDIT.md`](./docs/CAPABILITY_GAP_AUDIT.md).
|
|
386
584
|
|
|
387
585
|
<details>
|
|
@@ -405,11 +603,22 @@ PlainScript 1.0.2 closes most of the gap with TypeScript-class languages using i
|
|
|
405
603
|
|
|
406
604
|
</details>
|
|
407
605
|
|
|
606
|
+
**How the pieces fit together.** PlainScript is deliberately small: a handful
|
|
607
|
+
of verbs (`remember`, `give`, `if` / `otherwise`, `done`) plus the collections
|
|
608
|
+
and functions you just met. Everything is a value - numbers and strings,
|
|
609
|
+
comparisons, collections, lambdas, whole functions - so pieces nest instead of
|
|
610
|
+
needing new syntax: a lambda inside a list, a comparison handed to a filter, a
|
|
611
|
+
`make` function stored in a record. When a pattern repeats, extract it into a
|
|
612
|
+
`make` function (or a lambda), group related names into a module, and call the
|
|
613
|
+
abstraction the same way you call `show` or `jsonDecode`. The standard library
|
|
614
|
+
and the backend capabilities that follow are exactly this: vocabulary built on
|
|
615
|
+
the primitives above, available to every program.
|
|
616
|
+
|
|
408
617
|
---
|
|
409
618
|
|
|
410
619
|
## Backend Services
|
|
411
620
|
|
|
412
|
-
Everything in this section is compiled by the deterministic compiler
|
|
621
|
+
Everything in this section is compiled by the deterministic compiler - no rules, no AI, no hidden codegen.
|
|
413
622
|
|
|
414
623
|
### Databases
|
|
415
624
|
|
|
@@ -419,7 +628,7 @@ Portable databases (SQLite native or WebAssembly):
|
|
|
419
628
|
database "app.db" // probes better-sqlite3, falls back to sql.js
|
|
420
629
|
```
|
|
421
630
|
|
|
422
|
-
`plainscript install` verifies that `better-sqlite3` actually loads. If the native module cannot be used, PlainScript warns and continues on the pure-JavaScript WebAssembly engine (`sql.js`)
|
|
631
|
+
`plainscript install` verifies that `better-sqlite3` actually loads. Since 1.0.362 the native engine ships as an **optional dependency**: installing `plainscript-lang` can never fail because a native binary is missing for the platform (e.g. Android/Termux), and programs that never open a database start without it. If the native module cannot be used, PlainScript warns and continues on the pure-JavaScript WebAssembly engine (`sql.js`) - the same program runs unchanged. An engine can be forced explicitly:
|
|
423
632
|
|
|
424
633
|
```
|
|
425
634
|
database "app.db" using "native" // hard requirement: better-sqlite3
|
|
@@ -550,7 +759,9 @@ done
|
|
|
550
759
|
|
|
551
760
|
## Runtime Standard Library
|
|
552
761
|
|
|
553
|
-
No imports needed
|
|
762
|
+
No imports needed - these functions are built into the compiler. They are the
|
|
763
|
+
standard vocabulary of everyday work - JSON, files, time, strings - so the
|
|
764
|
+
first version of a program usually needs no dependency at all:
|
|
554
765
|
|
|
555
766
|
| PlainScript | Description |
|
|
556
767
|
|---|---|
|
|
@@ -577,6 +788,12 @@ No imports needed — these functions are built into the compiler:
|
|
|
577
788
|
|
|
578
789
|
## Web Applications
|
|
579
790
|
|
|
791
|
+
`web app` starts the HTTP stack available to every program. `route <method>
|
|
792
|
+
"<path>" ... done` registers an endpoint; `reply` (or `show`) sends a response,
|
|
793
|
+
`reply json ... done` sends JSON with `is`-style fields, and `start <port>`
|
|
794
|
+
serves it. `status <n>` sets the response code and `when nothing matches`
|
|
795
|
+
handles otherwise-unmatched requests.
|
|
796
|
+
|
|
580
797
|
```
|
|
581
798
|
web app
|
|
582
799
|
|
|
@@ -601,7 +818,7 @@ start 3000
|
|
|
601
818
|
The same `.pln` you run on Node compiles to a browser script. Drive a canvas,
|
|
602
819
|
handle keyboard, pointer, touch, and gamepad input, run `requestAnimationFrame`
|
|
603
820
|
loops with delta time, load images and audio, and call any JavaScript library
|
|
604
|
-
(Three.js, WebGL, WebGPU, Matter.js) through plain interop
|
|
821
|
+
(Three.js, WebGL, WebGPU, Matter.js) through plain interop - no bundler needed:
|
|
605
822
|
|
|
606
823
|
```plainscript
|
|
607
824
|
web app
|
|
@@ -633,8 +850,8 @@ done
|
|
|
633
850
|
`gamepads`, `droppedFiles`, `webSocketSend`, and the WebGL helpers
|
|
634
851
|
`webglContext`/`glShader`/`glProgram`/`glBuffer`) make canvas apps, games, and
|
|
635
852
|
DOM UI direct. The full browser
|
|
636
|
-
and game development guide
|
|
637
|
-
networking, persistence, and interop
|
|
853
|
+
and game development guide - input, loops, assets, audio, state, collision,
|
|
854
|
+
networking, persistence, and interop - is [docs/GAME-PROMPT.md](docs/GAME-PROMPT.md).
|
|
638
855
|
|
|
639
856
|
## Additional Backend Capabilities
|
|
640
857
|
|
|
@@ -776,16 +993,31 @@ show page.hasNext # true if another page exists
|
|
|
776
993
|
|
|
777
994
|
## Multi-File Projects
|
|
778
995
|
|
|
996
|
+
Programs grow into files. `import "./math.pln"` pulls a whole file into the
|
|
997
|
+
current one, `import { circleArea } from "./math.pln"` and `bring circleArea
|
|
998
|
+
from "./math.pln"` import specific names, and `export <name>` (or
|
|
999
|
+
`export <name> and <name>`) makes names available to other files:
|
|
1000
|
+
|
|
779
1001
|
```
|
|
780
1002
|
import "./math.pln"
|
|
781
1003
|
import "./utils.pln"
|
|
1004
|
+
import { circleArea } from "./math.pln"
|
|
1005
|
+
bring circleArea from "./math.pln"
|
|
782
1006
|
|
|
783
1007
|
show PI
|
|
784
1008
|
|
|
785
1009
|
show double(5)
|
|
786
1010
|
```
|
|
787
1011
|
|
|
788
|
-
|
|
1012
|
+
```
|
|
1013
|
+
remember PI as 3.14159
|
|
1014
|
+
make circleArea(r)
|
|
1015
|
+
give PI * r * r
|
|
1016
|
+
done
|
|
1017
|
+
export circleArea
|
|
1018
|
+
```
|
|
1019
|
+
|
|
1020
|
+
Imports are bundled per entry: `plainscript build` gives every source file its own standalone output under `dist/`, with imported code inlined. Functions, lambdas, records, and modules together are how you build your own vocabulary on top of the core verbs - a new reader puzzle (`validate(body, fields)`) is a one-line call, not a loop.
|
|
789
1021
|
|
|
790
1022
|
---
|
|
791
1023
|
|
|
@@ -818,7 +1050,7 @@ done
|
|
|
818
1050
|
|
|
819
1051
|
## WhatsApp Bots
|
|
820
1052
|
|
|
821
|
-
Full WhatsApp connectivity through Baileys
|
|
1053
|
+
Full WhatsApp connectivity through Baileys - the implementation package is installed automatically and never appears in source:
|
|
822
1054
|
|
|
823
1055
|
```
|
|
824
1056
|
whatsapp bot
|
|
@@ -842,7 +1074,7 @@ done
|
|
|
842
1074
|
```
|
|
843
1075
|
|
|
844
1076
|
- `login qr` prints a scannable QR code; `login pairing "<number>"` prints an enter-on-phone code instead. Pairing numbers are validated at compile time (digits only after normalization, 8–15 characters).
|
|
845
|
-
- `login pairing` also accepts a variable
|
|
1077
|
+
- `login pairing` also accepts a variable - prompt for the number at runtime instead of hard-coding it:
|
|
846
1078
|
|
|
847
1079
|
```
|
|
848
1080
|
ask "WhatsApp number: " as phone
|
|
@@ -865,7 +1097,7 @@ See [`examples/whatsapp-bot/`](./examples/whatsapp-bot/) for ready-to-link progr
|
|
|
865
1097
|
| PlainScript | Compiles to |
|
|
866
1098
|
|---|---|
|
|
867
1099
|
| `use express` | `const express = require('express');` |
|
|
868
|
-
| `use sqlite` | `
|
|
1100
|
+
| `use sqlite` | `let Database; … require('better-sqlite3')` (lazily loaded - the native engine is an optional backend) |
|
|
869
1101
|
| `use fs` | `const fs = require('fs');` |
|
|
870
1102
|
| `use path` | `const path = require('path');` |
|
|
871
1103
|
|
package/compiler/bundler.js
CHANGED
|
@@ -67,7 +67,7 @@ function resolveDependencies(entryPath) {
|
|
|
67
67
|
const order = []; // final compile order
|
|
68
68
|
|
|
69
69
|
function visit(absPath, stack) {
|
|
70
|
-
// Already fully processed
|
|
70
|
+
// Already fully processed - skip (handles duplicate imports)
|
|
71
71
|
if (visited.has(absPath)) return;
|
|
72
72
|
|
|
73
73
|
// File is in the current DFS stack → circular dependency
|
|
@@ -90,7 +90,7 @@ function resolveDependencies(entryPath) {
|
|
|
90
90
|
|
|
91
91
|
// Parse the file to discover its own imports.
|
|
92
92
|
// Annotate any tokenise/parse error with the filename so callers see
|
|
93
|
-
// "file.pln
|
|
93
|
+
// "file.pln - Line N, Column N: …" rather than a bare positional message.
|
|
94
94
|
const source = fs.readFileSync(absPath, 'utf8');
|
|
95
95
|
let tokens, ast;
|
|
96
96
|
try {
|
|
@@ -98,7 +98,7 @@ function resolveDependencies(entryPath) {
|
|
|
98
98
|
ast = parse(tokens);
|
|
99
99
|
} catch (err) {
|
|
100
100
|
const relPath = path.relative(process.cwd(), absPath) || path.basename(absPath);
|
|
101
|
-
throw new Error(`${relPath}
|
|
101
|
+
throw new Error(`${relPath} - ${err.message}`);
|
|
102
102
|
}
|
|
103
103
|
|
|
104
104
|
// Recurse into each import before processing this file (DFS)
|
|
@@ -109,7 +109,7 @@ function resolveDependencies(entryPath) {
|
|
|
109
109
|
visit(resolvedAbs, newStack);
|
|
110
110
|
}
|
|
111
111
|
|
|
112
|
-
// All dependencies are done
|
|
112
|
+
// All dependencies are done - add this file to the order
|
|
113
113
|
visited.add(absPath);
|
|
114
114
|
order.push({ absPath, ast });
|
|
115
115
|
}
|
package/compiler/cli.js
CHANGED
|
@@ -287,7 +287,7 @@ function ensurePackageJson(cwd = process.cwd()) {
|
|
|
287
287
|
}, null, 2) + '\n', 'utf8');
|
|
288
288
|
}
|
|
289
289
|
|
|
290
|
-
// v2.1.1
|
|
290
|
+
// v2.1.1 - verify that a freshly installed package actually LOADS on this
|
|
291
291
|
// machine. "better-sqlite3 present in node_modules" does not imply usable:
|
|
292
292
|
// its native binding may be missing for this platform or Node ABI (the
|
|
293
293
|
// Termux failure mode). The check runs in a child process so a hard crash
|
|
@@ -321,7 +321,7 @@ function installPackages(packages, cwd = process.cwd()) {
|
|
|
321
321
|
stdio: 'ignore',
|
|
322
322
|
});
|
|
323
323
|
dependencyCache.set(`${cwd}\0${bareName}`, true);
|
|
324
|
-
// v2.1.1
|
|
324
|
+
// v2.1.1 - "downloaded" and "usable" are different facts. Report both.
|
|
325
325
|
if (verifyPackageUsable(bareName, cwd)) {
|
|
326
326
|
console.log(`${clrGreen('✓')} ${pkg} installed`);
|
|
327
327
|
} else {
|
|
@@ -332,7 +332,7 @@ function installPackages(packages, cwd = process.cwd()) {
|
|
|
332
332
|
);
|
|
333
333
|
}
|
|
334
334
|
} catch (_) {
|
|
335
|
-
// v2.1.1
|
|
335
|
+
// v2.1.1 - better-sqlite3 is optional at install time: programs opened
|
|
336
336
|
// through the portable engine chain fall back to sql.js, so a native
|
|
337
337
|
// build failure must not abort setup.
|
|
338
338
|
if (bareName === 'better-sqlite3') {
|
|
@@ -366,7 +366,7 @@ function ensureDependencies(files, install = true) {
|
|
|
366
366
|
//
|
|
367
367
|
// Deterministic only: the lexer/parser/generator pipeline is the single
|
|
368
368
|
// authoritative compiler. Unsupported syntax produces a precise compiler
|
|
369
|
-
// error
|
|
369
|
+
// error - there is no second compilation path (v2.1.1).
|
|
370
370
|
function compile(filePath, options = {}) {
|
|
371
371
|
const absPath = path.resolve(filePath);
|
|
372
372
|
if (!fs.existsSync(absPath)) {
|
|
@@ -421,7 +421,7 @@ function compile(filePath, options = {}) {
|
|
|
421
421
|
// file in the OS temp dir could never see the project's node_modules. Passing
|
|
422
422
|
// every node_modules directory between the entry file and the filesystem root
|
|
423
423
|
// through NODE_PATH gives the child the exact same resolution the old
|
|
424
|
-
// project-local temp file had
|
|
424
|
+
// project-local temp file had - without ever writing into the project.
|
|
425
425
|
function nodeModulesSearchPaths(entryDir) {
|
|
426
426
|
const paths = [];
|
|
427
427
|
let dir = path.resolve(entryDir);
|
|
@@ -504,9 +504,9 @@ function buildOne(filePath, srcDir, outDir, options = {}) {
|
|
|
504
504
|
return path.relative(process.cwd(), outPath) || outPath;
|
|
505
505
|
}
|
|
506
506
|
|
|
507
|
-
// `plainscript build <file.pln> -o <out.js>`
|
|
507
|
+
// `plainscript build <file.pln> -o <out.js>` - compile one entry to an explicit
|
|
508
508
|
// output path (same compilation pipeline as buildOne, including source maps
|
|
509
|
-
// when requested). Valuable for browser payloads such as the v1.0.
|
|
509
|
+
// when requested). Valuable for browser payloads such as the v1.0.362
|
|
510
510
|
// requestAnimationFrame / addEventListener helpers, which are meant to run as
|
|
511
511
|
// a single script tag.
|
|
512
512
|
function writeOneFile(filePath, outputFile) {
|
|
@@ -536,7 +536,7 @@ function writeOneFile(filePath, outputFile) {
|
|
|
536
536
|
return path.relative(process.cwd(), outPath) || outPath;
|
|
537
537
|
}
|
|
538
538
|
|
|
539
|
-
// `plainscript build`
|
|
539
|
+
// `plainscript build` - TypeScript-style production build:
|
|
540
540
|
//
|
|
541
541
|
// Zero config (default):
|
|
542
542
|
// messi.pln → dist/messi.js (project-root sources)
|
|
@@ -619,7 +619,7 @@ function cmdNew(projectName) {
|
|
|
619
619
|
fs.mkdirSync(path.join(dir, 'public'));
|
|
620
620
|
fs.mkdirSync(path.join(dir, 'src'));
|
|
621
621
|
|
|
622
|
-
// src/app.pln
|
|
622
|
+
// src/app.pln - starter web app
|
|
623
623
|
fs.writeFileSync(path.join(dir, 'src', 'app.pln'), `web app
|
|
624
624
|
|
|
625
625
|
serve folder "public"
|
|
@@ -631,14 +631,14 @@ done
|
|
|
631
631
|
route get "/api/status"
|
|
632
632
|
reply json
|
|
633
633
|
status is "ok"
|
|
634
|
-
version is "1.0.
|
|
634
|
+
version is "1.0.362"
|
|
635
635
|
done
|
|
636
636
|
done
|
|
637
637
|
|
|
638
638
|
start 3000
|
|
639
639
|
`);
|
|
640
640
|
|
|
641
|
-
// package.json
|
|
641
|
+
// package.json - plain Node semantics; PlainScript itself is a devDependency and
|
|
642
642
|
// deployment only needs the generated dist/ output.
|
|
643
643
|
fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({
|
|
644
644
|
name,
|
|
@@ -746,7 +746,7 @@ function cmdInstall() {
|
|
|
746
746
|
function cmdDoctor() {
|
|
747
747
|
console.log('PlainScript doctor\n');
|
|
748
748
|
const check = (label, ok, detail = '') => {
|
|
749
|
-
const suffix = detail ? `
|
|
749
|
+
const suffix = detail ? ` - ${detail}` : '';
|
|
750
750
|
console.log(`${ok ? clrGreen('✓') : clrRed('✗')} ${label}${suffix}`);
|
|
751
751
|
};
|
|
752
752
|
check('Node.js', Boolean(process.version));
|
|
@@ -843,14 +843,14 @@ function cmdUpdate() {
|
|
|
843
843
|
// Check syntax of a PlainScript file without generating JavaScript or executing.
|
|
844
844
|
// Full validation of a single .pln entry: resolve imports, parse+generate every
|
|
845
845
|
// file in dependency order, and verify the emitted JavaScript is syntactically
|
|
846
|
-
// valid
|
|
846
|
+
// valid - all without writing anything to disk. Returns a deterministic
|
|
847
847
|
// result record; `deps` are the npm packages the sources require.
|
|
848
848
|
function validateSource(absPath) {
|
|
849
849
|
const rel = path.relative(process.cwd(), absPath) || absPath;
|
|
850
850
|
const t0 = Date.now();
|
|
851
851
|
try {
|
|
852
852
|
// resolveDependencies parses each file too, so a parse error anywhere in
|
|
853
|
-
// the import graph surfaces here with a "file.pln
|
|
853
|
+
// the import graph surfaces here with a "file.pln - Line:Col" prefix.
|
|
854
854
|
const files = resolveDependencies(absPath);
|
|
855
855
|
const context = createGenerationContext();
|
|
856
856
|
let js = files.map(({ ast }) => generate(ast, context)).filter(s => s.trim()).join('\n');
|
|
@@ -948,7 +948,7 @@ function cmdCheck(target, json) {
|
|
|
948
948
|
|
|
949
949
|
for (const r of results) {
|
|
950
950
|
if (r.ok) {
|
|
951
|
-
console.log(`${clrGreen('✓')} ${r.file}
|
|
951
|
+
console.log(`${clrGreen('✓')} ${r.file} - ok${clrDim(` (${r.ms}ms)`)}`);
|
|
952
952
|
} else {
|
|
953
953
|
console.log(`${clrRed('✗')} ${r.file}`);
|
|
954
954
|
console.error(r.error);
|
|
@@ -978,7 +978,7 @@ function cmdFmt(filePath) {
|
|
|
978
978
|
const source = fs.readFileSync(absPath, 'utf8');
|
|
979
979
|
const formatted = format(source);
|
|
980
980
|
if (source === formatted) {
|
|
981
|
-
console.log(`${clrDim('–')} ${filePath}
|
|
981
|
+
console.log(`${clrDim('–')} ${filePath} - already formatted.`);
|
|
982
982
|
} else {
|
|
983
983
|
fs.writeFileSync(absPath, formatted, 'utf8');
|
|
984
984
|
console.log(`${clrGreen('✓')} Formatted ${filePath}`);
|
|
@@ -998,7 +998,7 @@ function cmdHelp() {
|
|
|
998
998
|
async function main() {
|
|
999
999
|
const args = process.argv.slice(2);
|
|
1000
1000
|
|
|
1001
|
-
// Global flags
|
|
1001
|
+
// Global flags - recognized anywhere in the argument list.
|
|
1002
1002
|
const quiet = args.includes('--quiet');
|
|
1003
1003
|
const verbose = args.includes('--verbose');
|
|
1004
1004
|
const json = args.includes('--json');
|
|
@@ -1014,7 +1014,7 @@ async function main() {
|
|
|
1014
1014
|
switch (command) {
|
|
1015
1015
|
case 'run': await cmdRun(fileArg, positional.slice(2)); break;
|
|
1016
1016
|
case 'build': {
|
|
1017
|
-
// v1.0.
|
|
1017
|
+
// v1.0.362 - optional -o/--output <path>. "-o" is a single-dash flag, so
|
|
1018
1018
|
// it survives the "--filtered" positional list; pull it out here before
|
|
1019
1019
|
// building the positional file argument for cmdBuild.
|
|
1020
1020
|
let outputPath = null;
|