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
package/compiler/lexer.js CHANGED
@@ -15,6 +15,7 @@ const TOKEN = {
15
15
  ELSE: 'ELSE', // alias for otherwise
16
16
  DONE: 'DONE',
17
17
  END: 'END', // alias for done
18
+ DO: 'DO', // block-bodied lambda opener: (x) do ... done
18
19
  GREATER: 'GREATER',
19
20
  LESS: 'LESS',
20
21
  THAN: 'THAN',
@@ -33,11 +34,14 @@ const TOKEN = {
33
34
  EVERY: 'EVERY', // alias: "for every item in list"
34
35
  IN: 'IN',
35
36
  WHILE: 'WHILE',
37
+ REPEAT: 'REPEAT', // Natural intent repeat loop: repeat 5 times, repeat with x in list, repeat while, repeat until
38
+ UNTIL: 'UNTIL', // Natural intent repeat until <condition>
39
+ LOG_KW: 'LOG_KW', // alias for show: "log 'hello'"
36
40
  USE: 'USE',
37
41
  IMPORT: 'IMPORT',
38
42
  INCLUDE: 'INCLUDE', // alias for import: "include "./file.pln""
39
43
  LOAD: 'LOAD', // alias for import: "load "./file.pln""
40
- // v0.3 — Express runtime
44
+ // v0.3 - Express runtime
41
45
  WHEN: 'WHEN',
42
46
  SOMEONE: 'SOMEONE',
43
47
  VISITS: 'VISITS',
@@ -54,7 +58,7 @@ const TOKEN = {
54
58
  SERVE_STATIC: 'SERVE_STATIC', // alias for serve folder
55
59
  SERVE_PUBLIC: 'SERVE_PUBLIC', // alias for serve folder
56
60
  FOLDER: 'FOLDER',
57
- // v0.6 — Extended comparisons
61
+ // v0.6 - Extended comparisons
58
62
  ABOVE: 'ABOVE',
59
63
  BELOW: 'BELOW',
60
64
  AT: 'AT',
@@ -70,14 +74,14 @@ const TOKEN = {
70
74
  WITH: 'WITH',
71
75
  BETWEEN: 'BETWEEN',
72
76
  AND: 'AND',
73
- OR: 'OR', // v2.1.1 — logical or in conditions
74
- INSTANCEOF: 'INSTANCEOF', // v1.0.2 — instanceof condition
75
- // v0.6 — Express DX
77
+ OR: 'OR', // v2.1.1 - logical or in conditions
78
+ INSTANCEOF: 'INSTANCEOF', // v1.0.2 - instanceof condition
79
+ // v0.6 - Express DX
76
80
  WEB: 'WEB',
77
81
  ROUTE_KW: 'ROUTE_KW',
78
82
  START_KW: 'START_KW',
79
83
  RUN_ON: 'RUN_ON', // alias for start: "run on port 3000"
80
- // v0.6 — SQLite DX
84
+ // v0.6 - SQLite DX
81
85
  DATABASE_KW: 'DATABASE_KW',
82
86
  CONNECT_DB: 'CONNECT_DB', // alias for database: "connect database "app.db""
83
87
  USE_DATABASE: 'USE_DATABASE', // alias for database: "use database "app.db""
@@ -89,7 +93,7 @@ const TOKEN = {
89
93
  SQL_BODY: 'SQL_BODY', // raw SQL collected between a block keyword and "done"
90
94
  ASK: 'ASK', // interactive input: ask name / ask "prompt" as name
91
95
  PROMPT: 'PROMPT', // alias for ask: 'prompt "name?" as name'
92
- OCR_KW: 'OCR_KW', // v2.0.1 — ocr "<image>" as <name> [using "<lang>"]
96
+ OCR_KW: 'OCR_KW', // v2.0.1 - ocr "<image>" as <name> [using "<lang>"]
93
97
  PACKAGE: 'PACKAGE', // bare npm package name after "use" (may contain -, _, ., /, @)
94
98
  GATHER: 'GATHER', // gather each item in list giving expr (functional map)
95
99
  FILTER_KW: 'FILTER_KW', // filter each item in list when condition (functional filter)
@@ -102,10 +106,10 @@ const TOKEN = {
102
106
  EMIT: 'EMIT', // emit "event.name" with data (event emitter)
103
107
  HAPPENS: 'HAPPENS', // when "event.name" happens as data (event listener)
104
108
  CATCHES: 'CATCHES', // recover when err catches "TypeError" (typed error recovery)
105
- // v1.0.1 — generators. "yield" is a JavaScript reserved word, so it becomes a
109
+ // v1.0.1 - generators. "yield" is a JavaScript reserved word, so it becomes a
106
110
  // real keyword token (a variable named `yield` is illegal in JS anyway).
107
111
  YIELD: 'YIELD',
108
- // v2.3 — English-like syntax keywords
112
+ // v2.3 - English-like syntax keywords
109
113
  TO: 'TO', // "to add a and b together" function syntax
110
114
  TOGETHER: 'TOGETHER', // function block terminator alternative
111
115
  BE: 'BE', // "let x be 5" alternative to "let x is 5"
@@ -117,43 +121,44 @@ const TOKEN = {
117
121
  LIST_WITH: 'LIST_WITH', // "list with 1, 2, 3" alternative to "[1, 2, 3]"
118
122
  RECORD_WITH: 'RECORD_WITH', // "record with name 'Alice'" alternative to object literal
119
123
  // Punctuation
120
- LBRACE: 'LBRACE', // { — inline object literal (v1.2)
124
+ LBRACE: 'LBRACE', // { - inline object literal (v1.2)
121
125
  RBRACE: 'RBRACE', // }
122
- COLON: 'COLON', // : — inline object property separator (v1.2)
123
- ARROW: 'ARROW', // -> — Telegram inline keyboard button (v1.2)
126
+ COLON: 'COLON', // : - inline object property separator (v1.2)
127
+ ARROW: 'ARROW', // -> - Telegram inline keyboard button (v1.2)
124
128
  LPAREN: 'LPAREN',
125
129
  RPAREN: 'RPAREN',
126
130
  LBRACKET: 'LBRACKET',
127
131
  RBRACKET: 'RBRACKET',
128
132
  COMMA: 'COMMA',
129
133
  DOT: 'DOT',
130
- OPTIONAL_CHAIN: 'OPTIONAL_CHAIN', // ?. — optional chaining
131
- NULLISH_COALESCE: 'NULLISH_COALESCE', // ?? — nullish coalescing
132
- POWER: 'POWER', // ** — exponentiation
134
+ OPTIONAL_CHAIN: 'OPTIONAL_CHAIN', // ?. - optional chaining
135
+ NULLISH_COALESCE: 'NULLISH_COALESCE', // ?? - nullish coalescing
136
+ POWER: 'POWER', // ** - exponentiation
133
137
  PLUS: 'PLUS',
134
- MINUS: 'MINUS', // v2.1.1 — subtraction / unary minus
135
- STAR: 'STAR', // v2.1.1 — multiplication
136
- SLASH: 'SLASH', // v2.1.1 — division
137
- PERCENT: 'PERCENT', // v2.1.1 — remainder (modulo)
138
- SPREAD: 'SPREAD', // ... — spread operator
139
- REST: 'REST', // ... — rest parameter
138
+ MINUS: 'MINUS', // v2.1.1 - subtraction / unary minus
139
+ STAR: 'STAR', // v2.1.1 - multiplication
140
+ SLASH: 'SLASH', // v2.1.1 - division
141
+ PERCENT: 'PERCENT', // v2.1.1 - remainder (modulo)
142
+ SPREAD: 'SPREAD', // ... - spread operator
143
+ REST: 'REST', // ... - rest parameter
140
144
  LOGICAL_OR_ASSIGN: 'LOGICAL_OR_ASSIGN', // ||=
141
145
  LOGICAL_AND_ASSIGN: 'LOGICAL_AND_ASSIGN', // &&=
142
146
  NULLISH_ASSIGN: 'NULLISH_ASSIGN', // ??=
147
+ PLUS_ASSIGN: 'PLUS_ASSIGN', // ++= (increment-assign, x += v)
143
148
  // Literals & identifiers
144
149
  IDENTIFIER: 'IDENTIFIER',
145
150
  STRING: 'STRING',
146
151
  NUMBER: 'NUMBER',
147
- TRUE_KW: 'TRUE_KW', // v2.1.1 — boolean literal true
148
- FALSE_KW: 'FALSE_KW', // v2.1.1 — boolean literal false
149
- NULL_KW: 'NULL_KW', // v2.1.1 — null literal
150
- UNDEFINED_KW: 'UNDEFINED_KW', // v2.2.0 — undefined literal
152
+ TRUE_KW: 'TRUE_KW', // v2.1.1 - boolean literal true
153
+ FALSE_KW: 'FALSE_KW', // v2.1.1 - boolean literal false
154
+ NULL_KW: 'NULL_KW', // v2.1.1 - null literal
155
+ UNDEFINED_KW: 'UNDEFINED_KW', // v2.2.0 - undefined literal
151
156
  BIGINT: 'BIGINT', // BigInt literal (e.g., 42n)
152
157
  TEMPLATE_STRING: 'TEMPLATE_STRING', // backtick-delimited string with interpolation
153
158
  SYMBOL_KW: 'SYMBOL_KW', // symbol keyword
154
159
  DEBUGGER_KW: 'DEBUGGER_KW', // debugger keyword
155
160
  IMPORT_META: 'IMPORT_META', // import.meta
156
- // v2.4 — Near-English intent-oriented syntax (single-word keywords)
161
+ // v2.4 - Near-English intent-oriented syntax (single-word keywords)
157
162
  RAISES: 'RAISES', // "raise expr" throw alternative
158
163
  CHOOSING: 'CHOOSING', // "choosing cond then a otherwise b" ternary
159
164
  USES: 'USES', // "x uses a, b together" function call
@@ -176,6 +181,7 @@ const KEYWORDS = {
176
181
  else: TOKEN.ELSE,
177
182
  done: TOKEN.DONE,
178
183
  end: TOKEN.END,
184
+ do: TOKEN.DO, // block-bodied lambda opener: (x) do ... done
179
185
  greater: TOKEN.GREATER,
180
186
  less: TOKEN.LESS,
181
187
  than: TOKEN.THAN,
@@ -215,7 +221,7 @@ const KEYWORDS = {
215
221
  serve_static: TOKEN.SERVE_STATIC,
216
222
  serve_public: TOKEN.SERVE_PUBLIC,
217
223
  folder: TOKEN.FOLDER,
218
- // v0.6 — comparisons
224
+ // v0.6 - comparisons
219
225
  above: TOKEN.ABOVE,
220
226
  below: TOKEN.BELOW,
221
227
  at: TOKEN.AT,
@@ -233,25 +239,25 @@ const KEYWORDS = {
233
239
  instanceof: TOKEN.INSTANCEOF,
234
240
  now: TOKEN.NOW,
235
241
  back: TOKEN.BACK,
236
- // v2.1.1 — literal keywords. These were previously plain identifiers that
242
+ // v2.1.1 - literal keywords. These were previously plain identifiers that
237
243
  // passed through to generated JavaScript; making them explicit tokens gives
238
244
  // them first-class AST nodes and deterministic diagnostics.
239
245
  true: TOKEN.TRUE_KW,
240
246
  false: TOKEN.FALSE_KW,
241
247
  null: TOKEN.NULL_KW,
242
248
  undefined: TOKEN.UNDEFINED_KW,
243
- // v0.6 — Express DX
249
+ // v0.6 - Express DX
244
250
  web: TOKEN.WEB,
245
251
  route: TOKEN.ROUTE_KW,
246
252
  start: TOKEN.START_KW,
247
253
  run_on: TOKEN.RUN_ON,
248
- // v0.6 — SQLite DX
254
+ // v0.6 - SQLite DX
249
255
  database: TOKEN.DATABASE_KW,
250
256
  connect_db: TOKEN.CONNECT_DB,
251
257
  use_database: TOKEN.USE_DATABASE,
252
258
  ask: TOKEN.ASK,
253
259
  prompt: TOKEN.PROMPT,
254
- // v2.0.1 — OCR capability
260
+ // v2.0.1 - OCR capability
255
261
  ocr: TOKEN.OCR_KW,
256
262
  // IOPL-native features
257
263
  gather: TOKEN.GATHER,
@@ -268,7 +274,7 @@ const KEYWORDS = {
268
274
  yield: TOKEN.YIELD,
269
275
  symbol: TOKEN.SYMBOL_KW,
270
276
  debugger: TOKEN.DEBUGGER_KW,
271
- // v2.3 — English-like syntax keywords
277
+ // v2.3 - English-like syntax keywords
272
278
  to: TOKEN.TO,
273
279
  together: TOKEN.TOGETHER,
274
280
  be: TOKEN.BE,
@@ -279,12 +285,16 @@ const KEYWORDS = {
279
285
  divided_by: TOKEN.DIVIDED_BY_WORD,
280
286
  list_with: TOKEN.LIST_WITH,
281
287
  record_with: TOKEN.RECORD_WITH,
282
- // v2.4 — Near-English intent-oriented syntax (single-word keywords)
288
+ // v2.4 - Near-English intent-oriented syntax (single-word keywords)
283
289
  raise: TOKEN.RAISES,
284
290
  raises: TOKEN.RAISES,
285
291
  choosing: TOKEN.CHOOSING,
286
292
  uses: TOKEN.USES,
287
293
  fills: TOKEN.FILLS,
294
+ // Natural language intent keywords
295
+ repeat: TOKEN.REPEAT,
296
+ until: TOKEN.UNTIL,
297
+ log: TOKEN.LOG_KW,
288
298
  };
289
299
 
290
300
  // Keywords that introduce raw SQL blocks (content up to "done" is collected verbatim).
@@ -298,7 +308,7 @@ const SQL_BLOCK_WORDS = {
298
308
 
299
309
  // Decode one escape sequence inside a double-quoted string, starting at
300
310
  // source[index] (the backslash). Returns [decodedText, charsConsumed].
301
- // Supported: \n \t \r \0 \\ \" \' — any other escaped character is kept as
311
+ // Supported: \n \t \r \0 \\ \" \' - any other escaped character is kept as
302
312
  // itself (JavaScript-style leniency), so "\q" means "q".
303
313
  function decodeEscape(source, index) {
304
314
  const next = source[index + 1];
@@ -345,7 +355,7 @@ function tokenize(source) {
345
355
  pendingUse = false;
346
356
  continue;
347
357
  }
348
- pendingUse = false; // not a package start — tokenize normally
358
+ pendingUse = false; // not a package start - tokenize normally
349
359
  }
350
360
 
351
361
  // String literal. Normal escapes are decoded here (\n, \t, \r, \\, \",
@@ -380,7 +390,7 @@ function tokenize(source) {
380
390
  }
381
391
 
382
392
  // Backtick string (template literal): preserves whitespace and supports
383
- // interpolation. Scanning is escape-aware — a backslash escapes the next
393
+ // interpolation. Scanning is escape-aware - a backslash escapes the next
384
394
  // character verbatim (\` does not close the string, \\ stays a backslash,
385
395
  // \$ guards ${ from interpolating) while ordinary characters, real
386
396
  // newlines and ${expr} pass through untouched for the generator to emit.
@@ -411,6 +421,18 @@ function tokenize(source) {
411
421
  continue;
412
422
  }
413
423
 
424
+ // Hex number literal (0x... → decimal; supports colors like 0xRRGGBB)
425
+ if (source[i] === '0' && (source[i + 1] === 'x' || source[i + 1] === 'X')) {
426
+ let hex = '';
427
+ let j = i + 2;
428
+ while (j < source.length && /[0-9a-fA-F]/.test(source[j])) hex += source[j++];
429
+ if (hex) {
430
+ tokens.push({ type: TOKEN.NUMBER, value: Number.parseInt(hex, 16), line: tokenLine, col: tokenCol });
431
+ i = j;
432
+ continue;
433
+ }
434
+ }
435
+
414
436
  // Number literal (may include decimal point or BigInt suffix 'n')
415
437
  if (/[0-9]/.test(source[i])) {
416
438
  let num = '';
@@ -466,7 +488,7 @@ function tokenize(source) {
466
488
  tokens.push({ type: TOKEN.SQL_BODY, value: sql.trimEnd(), line: tokenLine, col: tokenCol });
467
489
  tokens.push({ type: TOKEN.DONE, value: 'done', line, col: col() });
468
490
  }
469
- // else: stays on same line — parsed normally by the parser as kwType + next tokens
491
+ // else: stays on same line - parsed normally by the parser as kwType + next tokens
470
492
  continue;
471
493
  }
472
494
 
@@ -492,9 +514,9 @@ function tokenize(source) {
492
514
  if (source[i] === '?' && source[i + 1] === '?') { tokens.push({ type: TOKEN.NULLISH_COALESCE, value: '??', line: tokenLine, col: tokenCol }); i += 2; continue; }
493
515
  if (source[i] === '.' && source[i + 1] === '.' && source[i + 2] === '.') { tokens.push({ type: TOKEN.SPREAD, value: '...', line: tokenLine, col: tokenCol }); i += 3; continue; }
494
516
  if (source[i] === '.') { tokens.push({ type: TOKEN.DOT, value: '.', line: tokenLine, col: tokenCol }); i++; continue; }
495
- if (source[i] === '+' && source[i + 1] === '+' && source[i + 2] === '=') { tokens.push({ type: TOKEN.LOGICAL_AND_ASSIGN, value: '++=', line: tokenLine, col: tokenCol }); i += 3; continue; }
517
+ if (source[i] === '+' && source[i + 1] === '+' && source[i + 2] === '=') { tokens.push({ type: TOKEN.PLUS_ASSIGN, value: '++=', line: tokenLine, col: tokenCol }); i += 3; continue; }
496
518
  if (source[i] === '+') { tokens.push({ type: TOKEN.PLUS, value: '+', line: tokenLine, col: tokenCol }); i++; continue; }
497
- // v2.1.1 — arithmetic. "->" is matched first so it never becomes MINUS.
519
+ // v2.1.1 - arithmetic. "->" is matched first so it never becomes MINUS.
498
520
  if (source[i] === '-' && source[i + 1] === '>') { tokens.push({ type: TOKEN.ARROW, value: '->', line: tokenLine, col: tokenCol }); i += 2; continue; }
499
521
  if (source[i] === '-') { tokens.push({ type: TOKEN.MINUS, value: '-', line: tokenLine, col: tokenCol }); i++; continue; }
500
522
  if (source[i] === '*' && source[i + 1] === '*') { tokens.push({ type: TOKEN.POWER, value: '**', line: tokenLine, col: tokenCol }); i += 2; continue; }