plainscript-lang 1.0.35 → 1.0.36

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 (87) hide show
  1. package/README.md +828 -209
  2. package/compiler/cli.js +68 -4
  3. package/compiler/generator.js +315 -0
  4. package/compiler/lexer.js +12 -0
  5. package/compiler/parser.js +144 -12
  6. package/compiler/version.js +1 -1
  7. package/docs/CAPABILITY_GAP_AUDIT.md +25 -4
  8. package/docs/GAME-PROMPT.md +915 -0
  9. package/docs/PLAINSCRIPT-SPEC.md +130 -1
  10. package/docs/index.html +21 -14
  11. package/docs/website/style.css +162 -195
  12. package/examples/ai-providers.pln +1 -1
  13. package/examples/arrays.pln +1 -1
  14. package/examples/async-errors.pln +1 -1
  15. package/examples/auth-api.pln +1 -1
  16. package/examples/auth-sessions.pln +1 -1
  17. package/examples/basics.pln +1 -1
  18. package/examples/bots.pln +1 -1
  19. package/examples/browser-interactive/README.md +29 -0
  20. package/examples/browser-interactive/public/index.html +83 -0
  21. package/examples/browser-interactive/public/interactive.js +27 -0
  22. package/examples/browser-interactive/src/interactive.pln +34 -0
  23. package/examples/cache-and-jobs.pln +1 -1
  24. package/examples/cache-schedule.pln +1 -1
  25. package/examples/canvas-game/README.md +34 -0
  26. package/examples/canvas-game/public/game.js +131 -0
  27. package/examples/canvas-game/public/index.html +48 -0
  28. package/examples/canvas-game/src/game.pln +139 -0
  29. package/examples/collections.pln +1 -1
  30. package/examples/concurrency.pln +1 -1
  31. package/examples/conditions.pln +1 -1
  32. package/examples/database.pln +1 -1
  33. package/examples/day2.pln +1 -1
  34. package/examples/day3.pln +1 -1
  35. package/examples/deployment.pln +1 -1
  36. package/examples/email-send.pln +1 -1
  37. package/examples/error-handling.pln +1 -1
  38. package/examples/expressions.pln +1 -1
  39. package/examples/file-uploads.pln +1 -1
  40. package/examples/files-and-config.pln +1 -1
  41. package/examples/files.pln +1 -1
  42. package/examples/football-backend/app.pln +1 -1
  43. package/examples/functions.pln +1 -1
  44. package/examples/hello.pln +1 -1
  45. package/examples/http-client.pln +1 -1
  46. package/examples/http.pln +1 -1
  47. package/examples/id-verification/app.pln +1 -1
  48. package/examples/javascript-library/README.md +54 -0
  49. package/examples/javascript-library/package-lock.json +21 -0
  50. package/examples/javascript-library/package.json +8 -0
  51. package/examples/javascript-library/public/config.json +4 -0
  52. package/examples/javascript-library/public/index.html +40 -0
  53. package/examples/javascript-library/src/interop.pln +53 -0
  54. package/examples/json.pln +1 -1
  55. package/examples/loops.pln +1 -1
  56. package/examples/modules/app.pln +1 -1
  57. package/examples/modules/main.pln +1 -1
  58. package/examples/modules/math.pln +1 -1
  59. package/examples/mongo.pln +1 -1
  60. package/examples/objects.pln +1 -1
  61. package/examples/ocr.pln +1 -1
  62. package/examples/packages.pln +1 -1
  63. package/examples/record-kinds.pln +1 -1
  64. package/examples/records.pln +1 -1
  65. package/examples/rest-api-fetch.pln +1 -1
  66. package/examples/rest-api.pln +1 -1
  67. package/examples/scheduled-tasks.pln +1 -1
  68. package/examples/search-and-filter.pln +1 -1
  69. package/examples/server.pln +1 -1
  70. package/examples/sessions-and-cookies.pln +1 -1
  71. package/examples/sqlite.pln +1 -1
  72. package/examples/start.pln +1 -1
  73. package/examples/stdlib.pln +1 -1
  74. package/examples/string-verbs.pln +1 -1
  75. package/examples/telegram-ai-bot.pln +1 -1
  76. package/examples/telegram-bot.pln +1 -1
  77. package/examples/testing.pln +1 -1
  78. package/examples/three-dimensional/README.md +51 -0
  79. package/examples/three-dimensional/public/index.html +33 -0
  80. package/examples/three-dimensional/src/scene.pln +34 -0
  81. package/examples/web-api.pln +1 -1
  82. package/examples/web-app.pln +1 -1
  83. package/examples/websocket-server.pln +1 -1
  84. package/examples/websocket.pln +1 -1
  85. package/examples/whatsapp-bot/pairing.pln +1 -1
  86. package/examples/whatsapp-bot/qr.pln +1 -1
  87. package/package.json +4 -3
@@ -41,8 +41,10 @@ const NUMBER_WORDS = {
41
41
  const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'];
42
42
 
43
43
  // Time units accepted by the "every <n> <unit>" statement, in milliseconds
44
- // (used by the generator to build the interval directly).
44
+ // (used by the generator to build the interval directly). "every 16
45
+ // milliseconds" powers requestAnimationFrame-style loops.
45
46
  const TIME_UNITS = {
47
+ millisecond: 1, milliseconds: 1,
46
48
  second: 1000, seconds: 1000,
47
49
  minute: 60 * 1000, minutes: 60 * 1000,
48
50
  hour: 60 * 60 * 1000, hours: 60 * 60 * 1000,
@@ -401,6 +403,13 @@ function parse(tokens) {
401
403
  peekAt(2).type === TOKEN.IDENTIFIER && TIME_UNITS[peekAt(2).value]) {
402
404
  return parseEvery();
403
405
  }
406
+ // v1.0.36 — every frame … done: requestAnimationFrame loop. "every" lexes
407
+ // as TOKEN.EACH; guard on the following "frame" identifier ("for every
408
+ // item in list" is intercepted by TOKEN.FOR above).
409
+ if (token.type === TOKEN.EACH && peekAt(1).type === TOKEN.IDENTIFIER &&
410
+ peekAt(1).value === 'frame') {
411
+ return parseEveryFrame();
412
+ }
404
413
  if (token.type === TOKEN.WHILE) return parseWhile();
405
414
  if (token.type === TOKEN.USE) return parseUse();
406
415
  if (token.type === TOKEN.IMPORT || token.type === TOKEN.INCLUDE || token.type === TOKEN.LOAD ||
@@ -544,9 +553,12 @@ function parse(tokens) {
544
553
  return { type: 'ReturnStatement', value };
545
554
  }
546
555
 
547
- // new expression: new ClassName(args)
556
+ // new expression: new ClassName(args). "new" is not a keyword, so
557
+ // parsePrimary intercepts it anywhere an expression appears; routing the
558
+ // statement-start form through parsePrimary keeps member chains after the
559
+ // constructor intact (new THREE.Scene().add(...)).
548
560
  if (token.value === 'new' && peekAt(1).type !== TOKEN.BECOMES && peekAt(1).type !== TOKEN.LPAREN) {
549
- return { type: 'ExpressionStatement', expression: parseNewExpression() };
561
+ return { type: 'ExpressionStatement', expression: parsePrimary() };
550
562
  }
551
563
 
552
564
  // v1.2 — bot "<token>" / bot <expr>: creates the polling Telegram bot.
@@ -643,6 +655,22 @@ function parse(tokens) {
643
655
  return parseEvery();
644
656
  }
645
657
 
658
+ // v1.0.36 — every frame … done: requestAnimationFrame loop. Identifier
659
+ // mirror of the EACH dispatch above.
660
+ if (token.value === 'every' && peekAt(1).type === TOKEN.IDENTIFIER &&
661
+ peekAt(1).value === 'frame') {
662
+ return parseEveryFrame();
663
+ }
664
+
665
+ // v1.0.36 — after <n> <unit>s … done: one-shot delayed execution.
666
+ // Contextual like "retry": "after becomes 5" and after(...) keep their
667
+ // ordinary meanings.
668
+ if (token.value === 'after' &&
669
+ tokenStartsValue(peekAt(1)) &&
670
+ peekAt(2).type === TOKEN.IDENTIFIER && TIME_UNITS[peekAt(2).value]) {
671
+ return parseAfter();
672
+ }
673
+
646
674
  // v2.1.0 — schedule "<cron>" … done: run work on a cron schedule.
647
675
  if (token.value === 'schedule' && peekAt(1).type === TOKEN.STRING) {
648
676
  advance(); // schedule
@@ -1854,6 +1882,31 @@ function parseAsk() {
1854
1882
  (nextToken.type === TOKEN.IDENTIFIER && (nextToken.value === 'nothing' || nextToken.value === 'socket'));
1855
1883
 
1856
1884
  if (!isEventWhen) {
1885
+ // v1.0.36 — when <target> "<event>" happens [as <name>] … done binds a
1886
+ // DOM event listener: when button "click" happens => addEventListener.
1887
+ // Detection probes the target expression and commits only when a string
1888
+ // followed by "happens" is next; otherwise the tokens are replayed and
1889
+ // the block parses as the English-like if-condition "when <condition>".
1890
+ const savedPos = pos;
1891
+ try {
1892
+ const target = parseExpression();
1893
+ if (peek().type === TOKEN.STRING && peekAt(1).type === TOKEN.HAPPENS) {
1894
+ const eventStr = advance().value;
1895
+ advance(); // happens
1896
+ let paramName = null;
1897
+ if (peek().type === TOKEN.AS) {
1898
+ advance(); // as
1899
+ paramName = consume(TOKEN.IDENTIFIER,
1900
+ 'Expected a parameter name after "as".\n\nExample:\n when button "click" happens as event').value;
1901
+ }
1902
+ const body = parseBody('"when happens" block');
1903
+ return { type: 'WhenTargetedStatement', target, event: eventStr, paramName, body };
1904
+ }
1905
+ } catch (_e) {
1906
+ // Not a targeted "when" — replay and fall through to the condition form.
1907
+ }
1908
+ pos = savedPos;
1909
+
1857
1910
  const condition = parseCondition();
1858
1911
  // Optional "then" keyword
1859
1912
  if (peek().type === TOKEN.THEN) {
@@ -2924,7 +2977,18 @@ function parseAsk() {
2924
2977
 
2925
2978
  const item = tryParseItemExpression();
2926
2979
  if (item) return item;
2927
- let node = parseAtom();
2980
+ // v1.0.36 — `new` works anywhere an expression is parsed (assignment
2981
+ // targets, call arguments, member chains). "new" is not a keyword, so this
2982
+ // identifier must be intercepted here; parseAtom would read it as a plain
2983
+ // Identifier and turn "new THREE.Scene()" into "new.THREE.Scene()".
2984
+ let node;
2985
+ if (peek().type === TOKEN.IDENTIFIER && peek().value === 'new' &&
2986
+ peekAt(1).type !== TOKEN.BECOMES && peekAt(1).type !== TOKEN.LPAREN) {
2987
+ advance(); // new
2988
+ node = parseNewExpressionCore();
2989
+ } else {
2990
+ node = parseAtom();
2991
+ }
2928
2992
  while (true) {
2929
2993
  if (peek().type === TOKEN.LBRACKET) {
2930
2994
  advance();
@@ -3372,7 +3436,7 @@ function parseAsk() {
3372
3436
  }
3373
3437
  if (unitToken.type !== TOKEN.IDENTIFIER || !TIME_UNITS[unitToken.value]) {
3374
3438
  throw new Error(makeError(
3375
- 'Expected a time unit after the number in "every".\n\nUnits: seconds, minutes, hours, days\n\nExample:\n every 5 minutes',
3439
+ 'Expected a time unit after the number in "every".\n\nUnits: milliseconds, seconds, minutes, hours, days\n\nExample:\n every 5 minutes',
3376
3440
  unitToken
3377
3441
  ));
3378
3442
  }
@@ -3381,6 +3445,36 @@ function parseAsk() {
3381
3445
  return { type: 'EveryStatement', count, unit, body };
3382
3446
  }
3383
3447
 
3448
+ // v1.0.36 — every frame … done: a requestAnimationFrame loop whose body runs
3449
+ // once per animation frame. The next frame is scheduled after the body so it
3450
+ // always runs (t is the frame timestamp, like the DOM's rAF callback).
3451
+ function parseEveryFrame() {
3452
+ advance(); // every/each
3453
+ advance(); // frame
3454
+ const body = parseBody('"every frame" block');
3455
+ return { type: 'EveryFrameStatement', body };
3456
+ }
3457
+
3458
+ // v1.0.36 — after <n> <unit>s … done: run work once after a delay.
3459
+ // after 5 seconds
3460
+ // show "butter!" ... done
3461
+ // The delay is a number expression ("after count seconds"); the unit is
3462
+ // consumed from TIME_UNITS so the generator can fold <n>*<unit> directly.
3463
+ function parseAfter() {
3464
+ advance(); // after
3465
+ const delay = parseExpression();
3466
+ const unitToken = peek();
3467
+ if (unitToken.type !== TOKEN.IDENTIFIER || !TIME_UNITS[unitToken.value]) {
3468
+ throw new Error(makeError(
3469
+ 'Expected a time unit after the delay in "after".\n\nUnits: milliseconds, seconds, minutes, hours, days\n\nExample:\n after 5 seconds\n show "later"\n done',
3470
+ unitToken
3471
+ ));
3472
+ }
3473
+ const unit = TIME_UNITS[advance().value];
3474
+ const body = parseBody('"after" block');
3475
+ return { type: 'AfterStatement', delay, unit, body };
3476
+ }
3477
+
3384
3478
  // v2.1.0 — websocket server on <port> … done
3385
3479
  //
3386
3480
  // websocket server on 8081
@@ -3917,17 +4011,55 @@ function parseAsk() {
3917
4011
  return { type: 'ClassDeclaration', name, superClass, body };
3918
4012
  }
3919
4013
 
3920
- // new ClassName(args)
3921
- function parseNewExpression() {
3922
- advance(); // new
3923
- const callee = parsePrimary();
4014
+ // new ClassName(args) — the constructor-call forms:
4015
+ // new Foo → new Foo()
4016
+ // new Foo(1, 2) → new Foo(1, 2)
4017
+ // new window.Thing(1, 2) → new window.Thing(1, 2)
4018
+ // new Foo().bar → new Foo().bar (postfix continues in parsePrimary)
4019
+ // Called with the "new" word already consumed. The callee is parsed as a
4020
+ // plain identifier plus a member chain so "new THREE.Scene(75)" binds the
4021
+ // argument list to the constructor — not to a member call.
4022
+ function parseNewExpressionCore() {
4023
+ const callee = parseNewCallee();
4024
+ let args = [];
3924
4025
  if (peek().type === TOKEN.LPAREN) {
3925
4026
  advance(); // (
3926
- const { separator, args } = parseArgList();
4027
+ const { separator, args: parsedArgs } = parseArgList();
3927
4028
  consume(TOKEN.RPAREN, 'Expected ")" to close the constructor call.');
3928
- return { type: 'NewExpression', callee, args };
4029
+ if (separator) {
4030
+ throw new Error(makeError(
4031
+ 'Constructor calls cannot use "to"/"from" arguments.\n\nExample:\n new THREE.PerspectiveCamera(75, 1.5, 0.1, 1000)',
4032
+ peek()
4033
+ ));
4034
+ }
4035
+ args = parsedArgs;
3929
4036
  }
3930
- return { type: 'NewExpression', callee, args: [] };
4037
+ return { type: 'NewExpression', callee, args };
4038
+ }
4039
+
4040
+ // The constructor name after "new": an identifier with an optional member
4041
+ // chain. Deliberately narrower than parsePrimary — a call paren following
4042
+ // the callee belongs to the constructor, so it is never consumed here.
4043
+ function parseNewCallee() {
4044
+ const token = peek();
4045
+ if (token.type !== TOKEN.IDENTIFIER || token.value === 'new') {
4046
+ throw new Error(makeError(
4047
+ 'Expected a class name after "new".\n\nExample:\n remember scene as new THREE.Scene()',
4048
+ token
4049
+ ));
4050
+ }
4051
+ advance();
4052
+ let node = { type: 'Identifier', name: token.value };
4053
+ while (peek().type === TOKEN.DOT) {
4054
+ advance();
4055
+ const propToken = peek();
4056
+ if (propToken.type === TOKEN.EOF || !/^[A-Za-z_$]/.test(propToken.value)) {
4057
+ throw new Error(makeError('Expected a property name after "." in the constructor.', propToken));
4058
+ }
4059
+ advance();
4060
+ node = { type: 'MemberExpression', object: node, property: propToken.value };
4061
+ }
4062
+ return node;
3931
4063
  }
3932
4064
 
3933
4065
  // ── Program ────────────────────────────────────────────────────────────────
@@ -1,6 +1,6 @@
1
1
  // Single source of truth for the compiler version.
2
2
  // Consumed by cli.js help/version output.
3
3
 
4
- const VERSION = '1.0.35';
4
+ const VERSION = '1.0.36';
5
5
 
6
6
  module.exports = { VERSION };
@@ -1,4 +1,4 @@
1
- # PlainScript 1.0.35 Capability Audit
1
+ # PlainScript 1.0.36 Capability Audit
2
2
 
3
3
  This audit is based on what the compiler actually supports right now.
4
4
  If `plainscript check` validates it, it's listed here.
@@ -66,6 +66,23 @@ If `plainscript check` validates it, it's listed here.
66
66
  | WhatsApp bots | Implemented | `whatsapp bot` (pairing/QR, message types, media download, custom Baileys) |
67
67
  | OCR | Implemented | `ocr path of file as text` |
68
68
 
69
+ ## Browser and Games
70
+
71
+ | Capability | Status | Current source form |
72
+ | --- | --- | --- |
73
+ | Static serving | Implemented | `web app`, `serve folder "public"`, `reply file "public/index.html"` |
74
+ | Browser compile target | Implemented | `build game.pln -o public/game.js` (package-free `<script>` output) |
75
+ | Canvas 2D | Implemented | `canvas.getContext("2d")`, `fillStyle becomes ...`, `fillRect(...)` |
76
+ | DOM events | Implemented | `when <target> "<event>" happens as name` → `addEventListener` |
77
+ | Frame loops | Implemented | `every frame ... done`, rAF + delta time |
78
+ | Browser builtins | Implemented | `select`, `selectAll`, `parseHTML`, `localPoint`, `gamepads`, `droppedFiles` |
79
+ | Promise builtins | Implemented | `loadImage`, `loadAudio`, `fetchJson`, `fetchBytes`, `readDataUrl` (auto-awaited) |
80
+ | Audio | Implemented | `audioContext()`, `playTone(freq, seconds, options)` (user-gesture resume) |
81
+ | WebSocket client | Implemented | `new WebSocket(url)`, `when ws "message" happens`, `webSocketSend(ws, value)` |
82
+ | Persistence | Implemented | `localStorage.getItem/setItem`, `jsonEncode`, `jsonDecode` |
83
+ | JS library interop | Implemented | `use <pkg>`, `bring name from "pkg"`, `new Type(...)`, callbacks, `try/recover` |
84
+ | WebGL/WebGPU and libraries | Implemented | `webglContext`/`glShader`/`glProgram`/`glBuffer`, `new THREE.Scene()` etc. |
85
+
69
86
  ## Canonical Examples
70
87
 
71
88
  Here are the example files that exercise each capability:
@@ -91,6 +108,10 @@ examples/cache-schedule.pln
91
108
  examples/bots.pln
92
109
  examples/ocr.pln
93
110
  examples/testing.pln
111
+ examples/canvas-game/
112
+ examples/browser-interactive/
113
+ examples/three-dimensional/
114
+ examples/javascript-library/
94
115
  examples/modules/
95
116
  examples/football-backend/
96
117
  examples/id-verification/
@@ -105,6 +126,6 @@ find examples -name '*.pln' -exec node compiler/cli.js check {} \;
105
126
 
106
127
  ## Version Info
107
128
 
108
- The release label for this repo is `1.0.35`. It covers the compiler,
109
- package metadata, website, and editor tooling. Third-party dependency
110
- versions are not tied to this label.
129
+ The release label for this repo is `1.0.36`. It covers the compiler,
130
+ package metadata, website, editor tooling, and browser/game documentation.
131
+ Third-party dependency versions are not tied to this label.