plainscript-lang 1.0.35 → 1.0.361

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 (92) hide show
  1. package/README.md +1052 -201
  2. package/compiler/bundler.js +4 -4
  3. package/compiler/cli.js +82 -18
  4. package/compiler/dependency-detector.js +34 -22
  5. package/compiler/generator.js +587 -172
  6. package/compiler/lexer.js +61 -39
  7. package/compiler/parser.js +685 -182
  8. package/compiler/sourcemap.js +1 -1
  9. package/compiler/version.js +1 -1
  10. package/docs/CAPABILITY_GAP_AUDIT.md +25 -4
  11. package/docs/FB-PROMPT.md +524 -0
  12. package/docs/GAME-PROMPT.md +916 -0
  13. package/docs/PLAINSCRIPT-SPEC.md +135 -5
  14. package/docs/index.html +28 -14
  15. package/docs/website/script.js +1 -1
  16. package/docs/website/style.css +162 -195
  17. package/examples/ai-providers.pln +1 -1
  18. package/examples/arrays.pln +1 -1
  19. package/examples/async-errors.pln +2 -1
  20. package/examples/auth-api.pln +1 -1
  21. package/examples/auth-sessions.pln +1 -1
  22. package/examples/basics.pln +1 -1
  23. package/examples/bots.pln +1 -1
  24. package/examples/browser-interactive/README.md +29 -0
  25. package/examples/browser-interactive/public/index.html +83 -0
  26. package/examples/browser-interactive/public/interactive.js +27 -0
  27. package/examples/browser-interactive/src/interactive.pln +34 -0
  28. package/examples/cache-and-jobs.pln +1 -1
  29. package/examples/cache-schedule.pln +1 -1
  30. package/examples/canvas-game/README.md +34 -0
  31. package/examples/canvas-game/public/game.js +131 -0
  32. package/examples/canvas-game/public/index.html +48 -0
  33. package/examples/canvas-game/src/game.pln +139 -0
  34. package/examples/collections.pln +1 -1
  35. package/examples/concurrency.pln +1 -1
  36. package/examples/conditions.pln +1 -1
  37. package/examples/database.pln +1 -1
  38. package/examples/day2.pln +1 -1
  39. package/examples/day3.pln +1 -1
  40. package/examples/deployment.pln +1 -1
  41. package/examples/email-send.pln +1 -1
  42. package/examples/error-handling.pln +3 -2
  43. package/examples/expressions.pln +1 -1
  44. package/examples/file-uploads.pln +1 -1
  45. package/examples/files-and-config.pln +1 -1
  46. package/examples/files.pln +1 -1
  47. package/examples/football-backend/app.pln +1 -1
  48. package/examples/functions.pln +1 -1
  49. package/examples/hello.pln +1 -1
  50. package/examples/http-client.pln +1 -1
  51. package/examples/http.pln +1 -1
  52. package/examples/id-verification/app.pln +1 -1
  53. package/examples/javascript-library/README.md +54 -0
  54. package/examples/javascript-library/package-lock.json +21 -0
  55. package/examples/javascript-library/package.json +8 -0
  56. package/examples/javascript-library/public/config.json +4 -0
  57. package/examples/javascript-library/public/index.html +40 -0
  58. package/examples/javascript-library/src/interop.pln +53 -0
  59. package/examples/json.pln +1 -1
  60. package/examples/loops.pln +1 -1
  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/objects.pln +1 -1
  66. package/examples/ocr.pln +1 -1
  67. package/examples/packages.pln +1 -1
  68. package/examples/record-kinds.pln +1 -1
  69. package/examples/records.pln +1 -1
  70. package/examples/rest-api-fetch.pln +1 -1
  71. package/examples/rest-api.pln +1 -1
  72. package/examples/scheduled-tasks.pln +1 -1
  73. package/examples/search-and-filter.pln +1 -1
  74. package/examples/server.pln +1 -1
  75. package/examples/sessions-and-cookies.pln +1 -1
  76. package/examples/sqlite.pln +1 -1
  77. package/examples/start.pln +1 -1
  78. package/examples/stdlib.pln +1 -1
  79. package/examples/string-verbs.pln +1 -1
  80. package/examples/telegram-ai-bot.pln +1 -1
  81. package/examples/telegram-bot.pln +1 -1
  82. package/examples/testing.pln +1 -1
  83. package/examples/three-dimensional/README.md +51 -0
  84. package/examples/three-dimensional/public/index.html +33 -0
  85. package/examples/three-dimensional/src/scene.pln +34 -0
  86. package/examples/web-api.pln +1 -1
  87. package/examples/web-app.pln +1 -1
  88. package/examples/websocket-server.pln +1 -1
  89. package/examples/websocket.pln +1 -1
  90. package/examples/whatsapp-bot/pairing.pln +2 -2
  91. package/examples/whatsapp-bot/qr.pln +2 -2
  92. package/package.json +9 -10
@@ -1,4 +1,4 @@
1
- # PlainScript 1.0.35 language specification
1
+ # PlainScript 1.0.361 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
@@ -230,6 +230,7 @@ recover as error
230
230
  show message of error
231
231
  finally
232
232
  show "finished"
233
+ done
233
234
 
234
235
  retry 3 times every 1 second
235
236
  show "retry"
@@ -311,7 +312,7 @@ accepts the following clauses:
311
312
  | Clause | Purpose |
312
313
  |--------|---------|
313
314
  | `auth "<folder>"` | Path where session credentials persist across restarts. |
314
- | `use baileys "<pkg>"` | Optional. Override the Baileys package (default: `@qwerty-xcv/baileys`). |
315
+ | `use baileys "<pkg>"` | Optional. Override the Baileys package (default: `@whiskeysockets/baileys`). |
315
316
  | `login qr` | Authenticate by scanning a QR code in the terminal. |
316
317
  | `login pairing "<phone>"` | Authenticate by entering a phone number (digits only, no `+`). The argument may also be an expression such as `env("WHATSAPP_PHONE")`. |
317
318
  | `on message ... done` | Handler that fires for every incoming message. |
@@ -326,7 +327,7 @@ include `message.text`, `message.type`, `message.mtype`, `message.caption`,
326
327
  ```plainscript
327
328
  whatsapp bot
328
329
  auth "plain-script-whatsapp"
329
- use baileys "@qwerty-xcv/baileys"
330
+ use baileys "@whiskeysockets/baileys"
330
331
  login pairing "2348012345678"
331
332
  on message
332
333
  if message.text is "/start"
@@ -377,12 +378,12 @@ documents, buttons, lists, and more. The following helpers are available:
377
378
  `"reaction"`, `"contact"`, `"contacts"`, `"location"`, `"live-location"`,
378
379
  `"poll"`, `"group-invite"`, and `"other"`.
379
380
 
380
- **Full example — media, buttons, and list replies:**
381
+ **Full example - media, buttons, and list replies:**
381
382
 
382
383
  ```plainscript
383
384
  whatsapp bot
384
385
  auth "plain-script-whatsapp"
385
- use baileys "@qwerty-xcv/baileys"
386
+ use baileys "@whiskeysockets/baileys"
386
387
  login pairing env("WHATSAPP_PHONE")
387
388
  on message
388
389
  log message
@@ -442,6 +443,134 @@ Chart options may include `width`, `height`, `background`, `foreground`,
442
443
  `grid`, `accent`, and `muted`. Image values are strings, so they can also be
443
444
  returned from a route or inserted into HTML.
444
445
 
446
+ ## Browser and games
447
+
448
+ PlainScript compiles to Plain JavaScript that runs in modern browsers. A
449
+ `web app` can serve the page itself, or you compile a `.pln` to `game.js` and
450
+ serve it with any static host. The tested workflows are:
451
+
452
+ 1. **Static**, served by PlainScript - `web app` + `serve folder "public"` +
453
+ a `reply file` route that returns `index.html`:
454
+
455
+ ```plainscript
456
+ web app
457
+ serve folder "public"
458
+ route get "/"
459
+ reply file "public/index.html"
460
+ done
461
+ start 8000
462
+ ```
463
+
464
+ 2. **Static**, any host - `node compiler/cli.js build game.pln -o public/game.js`
465
+ and include `<script src="game.js">` after the canvas and any CDN globals.
466
+
467
+ Canvas apps use the same value/property interop as everything else - canvas
468
+ state is assigned with `becomes`, then a draw call runs:
469
+
470
+ ```plainscript
471
+ remember canvas as document.getElementById("game")
472
+ remember ctx as canvas.getContext("2d")
473
+ ctx.fillStyle becomes "#0d1117"
474
+ ctx.fillRect(0, 0, 320, 240)
475
+ ```
476
+
477
+ Animation is `requestAnimationFrame`. Two native loop forms: `every frame`
478
+ (timing-agnostic) and an explicit rAF callback with delta seconds for
479
+ frame-rate-independent movement - see `docs/GAME-PROMPT.md` for the canonical
480
+ `dt` idiom. Input uses the DOM event form; `when <target> "<event>" happens`
481
+ becomes `addEventListener`, and reading a key map uses a boolean comparison:
482
+
483
+ ```plainscript
484
+ remember keys as {}
485
+ when document "keydown" happens as ke
486
+ keys[ke.key] becomes true
487
+ done
488
+ when document "keyup" happens as ke
489
+ keys[ke.key] becomes false
490
+ done
491
+
492
+ if keys["ArrowLeft"] is true
493
+ player.x becomes player.x - 4
494
+ done
495
+ ```
496
+
497
+ Browser builtins are either direct helpers or auto-awaited promises - no
498
+ `await` is written for the loaders:
499
+
500
+ - `select("canvas")` / `selectAll(".card")` / `parseHTML("<div>...</div>")`
501
+ - `loadImage(url)` → `Image`; `loadAudio(url)` → `Audio` element
502
+ - `fetchJson(url)` → `{ok, status, data, text, parseError}`; `fetchBytes(url)`
503
+ → `{ok, status, data: Uint8Array}`
504
+ - `readDataUrl(file)` → a `data:` URL string for a `File` (from
505
+ `droppedFiles(event)` or a file input)
506
+ - `audioContext()` + `playTone(frequency, seconds, options)` - start from a
507
+ user-gesture handler (`ctx.resume()`)
508
+ - `localPoint(event, canvas)` maps client to canvas coordinates
509
+ - `gamepads()` returns connected pads; `droppedFiles(event)` reads drag-drop
510
+ - WebSockets: client side uses `new WebSocket(url)` with `when ws "message"
511
+ happens`, and `webSocketSend(ws, value)` sends strings as-is or
512
+ JSON-stringifies anything else
513
+ - Persistence is direct interop: `localStorage.getItem(...)` /
514
+ `setItem` plus `jsonEncode` / `jsonDecode` (JSON is a builtin data type)
515
+
516
+ WebGL runs through the WebGL2 canvas API (`webglContext(canvas)`, `glShader`,
517
+ `glProgram`, `glBuffer` - all protected by teaching errors) or a library such
518
+ as Three.js constructed interop-style with `new`. WebGPU is available via its
519
+ canvas API.
520
+ A detailed, expanding guide for browser games lives in
521
+ `docs/GAME-PROMPT.md`.
522
+
523
+ ## JavaScript interop
524
+
525
+ `.pln` files are JavaScript; any JS API is reachable without sugar. Importing
526
+ uses `use` (bare npm name, bound lowercase) or `bring name from "pkg"`:
527
+
528
+ ```plainscript
529
+ use matter
530
+ bring THREE from "three"
531
+ remember engine as matter.Engine.create()
532
+ remember scene as new THREE.Scene()
533
+ ```
534
+
535
+ Call anything - member chains need no special syntax, and there is no wrapper
536
+ around values:
537
+
538
+ ```plainscript
539
+ crypto.createHash("sha256").update("abc").digest("hex")
540
+ mesh.scale.set(2, 2, 2)
541
+ ```
542
+
543
+ Construct with `new Type(args)` - as a statement, in `remember`, as an
544
+ argument, or bare without parens (`new Enemy`). A `make` function reference is
545
+ a first-class value - pass it as a callback:
546
+
547
+ ```plainscript
548
+ make fitWindow()
549
+ camera.aspect becomes window.innerWidth / window.innerHeight
550
+ camera.updateProjectionMatrix()
551
+ done
552
+ window.addEventListener("resize", fitWindow)
553
+ ```
554
+
555
+ Promises are awaited with `await` / `wait for`; errors follow the `try` /
556
+ `recover as err` / `finally` idiom, never `.then` chaining:
557
+
558
+ ```plainscript
559
+ try
560
+ remember response as await fetch("/api/state")
561
+ remember data as await response.json()
562
+ show data
563
+ recover as err
564
+ show message of err
565
+ done
566
+ ```
567
+
568
+ Typed arrays construct and index like anything else
569
+ (`new Uint8Array(64)`, `buffer[0] becomes 255`). The generated file adds
570
+ `require()` only for `use`/`bring`, and ends with a guarded `module.exports`
571
+ tail so the same output works as a browser `<script>` and under Node. The
572
+ comprehensive guide is `docs/GAME-PROMPT.md`.
573
+
445
574
  ## Native tests
446
575
 
447
576
  ```plainscript
@@ -457,6 +586,7 @@ Assertions are `equals`, `is`, `contains`, and `raises`.
457
586
  ```text
458
587
  plainscript check [target]
459
588
  plainscript build [file.pln]
589
+ plainscript build <file.pln> -o <output.js>
460
590
  plainscript run <file.pln>
461
591
  plainscript start
462
592
  plainscript fmt <file.pln>
package/docs/index.html CHANGED
@@ -3,13 +3,13 @@
3
3
  <head>
4
4
  <meta charset="utf-8">
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1">
6
- <meta name="description" content="PlainScript 1.0.35 language reference and examples">
6
+ <meta name="description" content="PlainScript 1.0.361 language reference and examples">
7
7
  <meta name="theme-color" content="#070c16">
8
- <title>PlainScript 1.0.35</title>
8
+ <title>PlainScript 1.0.361</title>
9
9
 
10
10
  <link rel="preconnect" href="https://fonts.googleapis.com">
11
11
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
12
- <link href="https://fonts.googleapis.com/css2?family=Roboto+Mono:wght@500&display=swap" rel="stylesheet">
12
+ <link href="https://fonts.googleapis.com/css2?family=Newsreader:opsz,wght@6..72,400;6..72,500&family=Public+Sans:wght@400;500&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
13
13
  <link rel="stylesheet" href="website/style.css">
14
14
  </head>
15
15
  <body>
@@ -21,7 +21,7 @@
21
21
  <a class="nav-logo" href="#">
22
22
  <img class="nav-logo-image" src="logo-pln.jpg" alt="">
23
23
  <span>PlainScript</span>
24
- <span class="logo-ver">1.0.35</span>
24
+ <span class="logo-ver">1.0.361</span>
25
25
  </a>
26
26
  <button class="nav-toggle" id="nav-toggle" aria-label="Toggle navigation" aria-expanded="false" aria-controls="nav-links">
27
27
  <span class="nav-toggle-bar"></span>
@@ -40,17 +40,24 @@
40
40
  <main>
41
41
  <section class="hero">
42
42
  <div class="container hero-content">
43
- <p class="hero-badge" data-reveal>1.0.35: Node.js programming for everyone</p>
44
- <h1 class="hero-title">Code that reads like plain English.</h1>
45
- <p class="hero-lead">Write what you want in plain words. PlainScript turns it into JavaScript — simple, readable, and easy to check.</p>
46
- <div class="hero-actions">
47
- <a class="button button-primary" href="#quickstart">Start building</a>
48
- <a class="button button-secondary" href="#library">Browse examples</a>
49
- </div>
50
- <pre class="code-window"><code>remember name as "Ada"
43
+ <div class="hero-grid">
44
+ <div class="hero-headline-block">
45
+ <p class="hero-badge" data-reveal>an intent-oriented language for node.js</p>
46
+ <h1 class="hero-title"><span class="kw">remember</span> the sentence <span class="kw">as</span> the program.<br><span class="kw">show</span> the result <span class="kw">when</span> the meaning is clear.</h1>
47
+ <p class="hero-lead">Write what you want in plain words. PlainScript checks it, then turns it into readable JavaScript - no boilerplate, no hidden steps.</p>
48
+ <div class="hero-actions">
49
+ <span class="hero-install-label">install</span>
50
+ <a class="button" href="#quickstart">npx plainscript new hello</a>
51
+ </div>
52
+ </div>
53
+ <div class="hero-panel">
54
+ <p class="hero-panel-label">terminal</p>
55
+ <pre class="code-window"><code>remember name as "Ada"
51
56
  if name contains "A"
52
57
  show `Hello, ${name}!`
53
58
  done</code></pre>
59
+ </div>
60
+ </div>
54
61
  </div>
55
62
  </section>
56
63
 
@@ -75,14 +82,21 @@ npm start</code></pre>
75
82
  <div class="container">
76
83
  <p class="section-tag" data-reveal>Language</p>
77
84
  <h2 class="section-title" data-reveal>A small set of words you already know.</h2>
85
+ <p class="section-lead" data-reveal>Every construct is a sentence: a verb opens a block, <code>done</code> closes it, and values, functions, and collections nest freely - a comparison, a lambda, and a list all fit anywhere a value fits.</p>
78
86
  <div class="feature-grid">
79
87
  <article class="feature-card" data-reveal><h3>Variables</h3><p>Store values with <code>remember name as "Ada"</code> and change them with <code>becomes</code>.</p></article>
80
88
  <article class="feature-card" data-reveal><h3>Conditions</h3><p>Compare things with <code>is at least</code>, <code>contains</code>, <code>between</code>, and more.</p></article>
89
+ <article class="feature-card" data-reveal><h3>Choice</h3><p>Pick a value inline with <code>choosing ok is true then "online" otherwise "offline"</code>, or an <code>if / otherwise</code> block for steps.</p></article>
81
90
  <article class="feature-card" data-reveal><h3>Functions</h3><p>Create functions with <code>make</code>, return with <code>give</code>, and close with <code>done</code>.</p></article>
91
+ <article class="feature-card" data-reveal><h3>Lambdas</h3><p>Write snippets as values: <code>(n) -> n * 2</code>, or a block with <code>(n) do ... done</code>.</p></article>
92
+ <article class="feature-card" data-reveal><h3>Loops</h3><p>Iterate with <code>for each item in list</code>, <code>for index i from 0 to 9</code>, or <code>repeat N times</code>.</p></article>
82
93
  <article class="feature-card" data-reveal><h3>Records</h3><p>Model your data with record kinds and easy constructors.</p></article>
83
94
  <article class="feature-card" data-reveal><h3>Modules</h3><p>Import code with <code>bring ... from</code>, <code>@/</code> aliases, and re-exports.</p></article>
84
95
  <article class="feature-card" data-reveal><h3>Compound Types</h3><p>Use dictionaries, sets, and tuples with unpacking.</p></article>
96
+ <article class="feature-card" data-reveal><h3>Errors</h3><p>Guard against failure with <code>try / recover as err / finally</code> and <code>raise</code>.</p></article>
97
+ <article class="feature-card" data-reveal><h3>Async and events</h3><p>Await promises with <code>wait for</code>, and bind events with <code>when element "click" happens</code>.</p></article>
85
98
  <article class="feature-card" data-reveal><h3>Web apps</h3><p>Set up routes, JSON responses, sessions, cookies, uploads, and auth.</p></article>
99
+ <article class="feature-card" data-reveal><h3>HTTP client</h3><p>Call APIs with <code>get url</code> / <code>post url with body</code> and read <code>status of response</code>.</p></article>
86
100
  <article class="feature-card" data-reveal><h3>Data and async</h3><p>Work with SQLite, HTTP, files, schedules, concurrency, and WebSockets.</p></article>
87
101
  <article class="feature-card" data-reveal><h3>AI providers</h3><p>Call Groq and other OpenAI-compatible providers using your own keys.</p></article>
88
102
  </div>
@@ -103,7 +117,7 @@ npm start</code></pre>
103
117
  <div class="container">
104
118
  <p class="section-tag" data-reveal>Feature library</p>
105
119
  <h2 class="section-title" data-reveal>Examples you can try today.</h2>
106
- <p class="section-lead">These snippets use the PlainScript 1.0.35 grammar.</p>
120
+ <p class="section-lead">These snippets use the PlainScript 1.0.361 grammar.</p>
107
121
  <div class="library-toolbar" data-reveal>
108
122
  <label class="sr-only" for="lib-search">Search examples</label>
109
123
  <input id="lib-search" class="lib-search-input" type="search" placeholder="Search examples">
@@ -132,7 +146,7 @@ npm start</code></pre>
132
146
  </main>
133
147
 
134
148
  <footer class="site-footer">
135
- <div class="container footer-bottom"><span>PlainScript</span><span>1.0.35</span></div>
149
+ <div class="container footer-bottom"><span>PlainScript</span><span>1.0.361</span></div>
136
150
  </footer>
137
151
 
138
152
  <script src="https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.min.js"></script>
@@ -288,7 +288,7 @@
288
288
  { category: "web", name: "Web routes", description: "Build an HTTP app with JSON routes.", source: 'web app\nroute get "/health"\n reply json\n ok is true\n done\ndone\nstart 3000' },
289
289
  { category: "web", name: "HTTP client", description: "Fetch data from a URL.", source: 'remember response as get "https://example.com/data" timeout 5000\nshow response.status' },
290
290
  { category: "web", name: "Auth and sessions", description: "Protect routes and track visitors.", source: 'web app\nenable sessions "session-secret"\nrequire api key from env("API_KEY")\nroute get "/me"\n reply json\n user is user of session of request\n done\ndone' },
291
- { category: "runtime", name: "Async errors", description: "Handle errors gracefully.", source: 'try\n remember result as get "https://example.com" timeout 5000\nrecover as error\n show message of error\nfinally\n show "finished"' },
291
+ { category: "runtime", name: "Async errors", description: "Handle errors gracefully.", source: 'try\n remember result as get "https://example.com" timeout 5000\nrecover as error\n show message of error\nfinally\n show "finished"\ndone' },
292
292
  { category: "runtime", name: "Concurrency", description: "Run several tasks at once.", source: 'remember results as allOf(list with firstJob(), secondJob())\nremember quick as withTimeout(firstJob(), 1000)\nshow results' },
293
293
  { category: "runtime", name: "WebSockets", description: "Chat and push updates live.", source: 'websocket server on 8080\n when socket connects\n send socket "connected"\n done\n when socket sends message\n broadcast message\n done\ndone' },
294
294
  { category: "runtime", name: "Cache", description: "Keep values ready with a TTL.", source: 'cache env("REDIS_URL")\ncacheSet("status", "ready", 60)\nremember status as cacheGet("status")' },