plainscript-lang 0.1.7 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +97 -39
  2. package/compiler/bundler.js +1 -1
  3. package/compiler/cli.js +44 -42
  4. package/compiler/generator.js +826 -16
  5. package/compiler/lexer.js +31 -2
  6. package/compiler/parser.js +548 -22
  7. package/compiler/version.js +1 -1
  8. package/docs/CAPABILITY_GAP_AUDIT.md +439 -0
  9. package/docs/PLINJS_SPEC.md +124 -24
  10. package/docs/index.html +535 -2205
  11. package/docs/website/script.js +889 -133
  12. package/docs/website/style.css +652 -1113
  13. package/examples/auth-api.ps +56 -0
  14. package/examples/{cache-and-jobs.pln → cache-and-jobs.ps} +1 -1
  15. package/examples/concurrency.ps +49 -0
  16. package/examples/{database.pln → database.ps} +1 -1
  17. package/examples/{deployment.pln → deployment.ps} +1 -1
  18. package/examples/{email-send.pln → email-send.ps} +1 -1
  19. package/examples/error-handling.ps +54 -0
  20. package/examples/file-uploads.ps +39 -0
  21. package/examples/files-and-config.ps +47 -0
  22. package/examples/http-client.ps +44 -0
  23. package/examples/modules/app.ps +16 -0
  24. package/examples/modules/math.ps +20 -0
  25. package/examples/record-kinds.ps +43 -0
  26. package/examples/{rest-api.pln → rest-api.ps} +1 -1
  27. package/examples/{scheduled-tasks.pln → scheduled-tasks.ps} +1 -1
  28. package/examples/search-and-filter.ps +34 -0
  29. package/examples/sessions-and-cookies.ps +54 -0
  30. package/examples/{websocket-server.pln → websocket-server.ps} +1 -1
  31. package/package.json +2 -2
  32. package/docs/website/index.html +0 -1500
  33. /package/examples/{arrays.pln → arrays.ps} +0 -0
  34. /package/examples/{day2.pln → day2.ps} +0 -0
  35. /package/examples/{day3.pln → day3.ps} +0 -0
  36. /package/examples/{expressions.pln → expressions.ps} +0 -0
  37. /package/examples/football-backend/{app.pln → app.ps} +0 -0
  38. /package/examples/{hello.pln → hello.ps} +0 -0
  39. /package/examples/id-verification/{app.pln → app.ps} +0 -0
  40. /package/examples/{loops.pln → loops.ps} +0 -0
  41. /package/examples/{objects.pln → objects.ps} +0 -0
  42. /package/examples/{rest-api-fetch.pln → rest-api-fetch.ps} +0 -0
  43. /package/examples/{server.pln → server.ps} +0 -0
  44. /package/examples/{start.pln → start.ps} +0 -0
  45. /package/examples/{stdlib.pln → stdlib.ps} +0 -0
  46. /package/examples/{telegram-bot.pln → telegram-bot.ps} +0 -0
  47. /package/examples/{web-app.pln → web-app.ps} +0 -0
  48. /package/examples/whatsapp-bot/{pairing.pln → pairing.ps} +0 -0
  49. /package/examples/whatsapp-bot/{qr.pln → qr.ps} +0 -0
@@ -8,6 +8,7 @@ const STATEMENT_KEYWORDS = [
8
8
  'for', 'while', 'use', 'import', 'when', 'listen', 'reply', 'serve',
9
9
  'web', 'route', 'start', 'database', 'query', 'insert', 'update', 'delete', 'execute',
10
10
  'ask', 'javascript', 'bot', 'ocr', 'try', 'recover', 'retry',
11
+ 'gather', 'filter', 'total', 'match', 'emit', 'stream', 'run',
11
12
  ];
12
13
 
13
14
  // Number words used by the numbered item expression (v1.1):
@@ -268,6 +269,9 @@ function parse(tokens) {
268
269
  if (token.type === TOKEN.IF) return parseIf();
269
270
  if (token.type === TOKEN.MAKE) return parseMake();
270
271
  if (token.type === TOKEN.GIVE) return parseGive();
272
+ // v1.0.0 — generators: `yield <expr>` is only meaningful inside a function
273
+ // body; the generator marks the enclosing `make ... done` as a function*.
274
+ if (token.type === TOKEN.YIELD) return parseYield();
271
275
  if (token.type === TOKEN.FOR) return parseForEach();
272
276
  // v2.1.0 — every <n> <unit>s … done: interval scheduling. "every" also
273
277
  // lexes as TOKEN.EACH (the "for every" alias), so only the number+unit
@@ -310,6 +314,14 @@ function parse(tokens) {
310
314
  if (token.type === TOKEN.DELETE_KW) return parseSqlBlock('delete', 'DeleteStatement');
311
315
  if (token.type === TOKEN.EXECUTE_KW) return parseSqlBlock('execute', 'ExecuteStatement');
312
316
 
317
+ // IOPL-native features
318
+ if (token.type === TOKEN.GATHER) return parseGatherStatement();
319
+ if (token.type === TOKEN.FILTER_KW) return parseFilterStatement();
320
+ if (token.type === TOKEN.TOTAL) return parseTotalStatement();
321
+ if (token.type === TOKEN.MATCH) return parseMatchStatement();
322
+ if (token.type === TOKEN.EMIT) return parseEmitStatement();
323
+ if (token.type === TOKEN.STREAM) return parseStreamStatement();
324
+
313
325
  if (token.type === TOKEN.EOF) return null;
314
326
 
315
327
  // Statements starting with an identifier: call, becomes, index/member becomes
@@ -422,6 +434,12 @@ function parse(tokens) {
422
434
  return { type: 'RunBackgroundStatement', call };
423
435
  }
424
436
 
437
+ // run in parallel ... done as <name>: worker threads with a result name.
438
+ if (token.value === 'run' &&
439
+ peekAt(1).type === TOKEN.IN && peekAt(2).type === TOKEN.PARALLEL) {
440
+ return parseRunParallelStatement();
441
+ }
442
+
425
443
  // v2.1.0 — websocket server on <port> … done: realtime endpoint.
426
444
  if (token.value === 'websocket' &&
427
445
  peekAt(1).type === TOKEN.IDENTIFIER && peekAt(1).value === 'server') {
@@ -474,6 +492,15 @@ function parse(tokens) {
474
492
  return { type: 'StatusStatement', value };
475
493
  }
476
494
 
495
+ // v2.2.0 — redirect to "<url>": sends an HTTP redirect from a route
496
+ // handler. "redirect(...)" calls and "redirect becomes x" stay ordinary.
497
+ if (token.value === 'redirect' && peekAt(1).value === 'to') {
498
+ advance(); // redirect
499
+ advance(); // to
500
+ const url = parseExpression();
501
+ return { type: 'RedirectStatement', url };
502
+ }
503
+
477
504
  // ── v2.1.1 statements (all contextual, following the v2.1.0 pattern) ──
478
505
 
479
506
  // try … [recover [as <name>]] … done: deterministic error handling.
@@ -551,6 +578,45 @@ function parse(tokens) {
551
578
  return { type: 'GoogleOAuthStatement', options: parsePropertyList('"google oauth" block') };
552
579
  }
553
580
 
581
+ // ── v1.0.0 — capability-gap features (all contextual, IOPL-native) ──
582
+
583
+ // define a kind called "Person" with … done → record schema (classes)
584
+ if (token.value === 'define' &&
585
+ peekAt(1).type === TOKEN.IDENTIFIER && peekAt(1).value === 'a') {
586
+ return parseDefineKind();
587
+ }
588
+
589
+ // load env file "<path>" → apply .env KEY=VALUE pairs to process.env
590
+ if (token.value === 'load' &&
591
+ peekAt(1).type === TOKEN.IDENTIFIER && peekAt(1).value === 'env' &&
592
+ peekAt(2).type === TOKEN.IDENTIFIER && peekAt(2).value === 'file') {
593
+ advance(); // load
594
+ advance(); // env
595
+ advance(); // file
596
+ const path = consume(TOKEN.STRING,
597
+ 'Expected an env file path string after "load env file".\n\nExample:\n load env file ".env"');
598
+ return { type: 'LoadEnvFileStatement', path: path.value };
599
+ }
600
+
601
+ // test "<name>" … done → native test DSL
602
+ if (token.value === 'test' && peekAt(1).type === TOKEN.STRING) {
603
+ return parseTestStatement();
604
+ }
605
+
606
+ // check … → assertion, only valid inside a test block
607
+ if (token.value === 'check') {
608
+ return parseCheckStatement();
609
+ }
610
+
611
+ // export <name> → mark a top-level symbol for module.exports
612
+ if (token.value === 'export' &&
613
+ peekAt(1).type === TOKEN.IDENTIFIER &&
614
+ peekAt(2).type !== TOKEN.LPAREN) {
615
+ advance(); // export
616
+ const name = advance().value;
617
+ return { type: 'ExportStatement', name };
618
+ }
619
+
554
620
  const expr = parsePrimary();
555
621
 
556
622
  if (peek().type === TOKEN.BECOMES) {
@@ -757,20 +823,150 @@ function parse(tokens) {
757
823
  function parseParamList() {
758
824
  const params = [];
759
825
  if (peek().type === TOKEN.RPAREN) return params;
760
- params.push(consume(TOKEN.IDENTIFIER, 'Expected a parameter name.').value);
826
+ const firstName = consume(TOKEN.IDENTIFIER, 'Expected a parameter name.').value;
827
+ const firstParam = { name: firstName };
828
+ if (peek().type === TOKEN.AS) {
829
+ advance(); // as
830
+ const dv = parseDefaultValue();
831
+ if (dv) firstParam.defaultValue = dv;
832
+ }
833
+ params.push(firstParam);
761
834
  while (peek().type === TOKEN.COMMA) {
762
835
  advance();
763
- params.push(consume(TOKEN.IDENTIFIER, 'Expected a parameter name after ",".').value);
836
+ const pName = consume(TOKEN.IDENTIFIER, 'Expected a parameter name after ",".').value;
837
+ const param = { name: pName };
838
+ if (peek().type === TOKEN.AS) {
839
+ advance(); // as
840
+ const dv = parseDefaultValue();
841
+ if (dv) param.defaultValue = dv;
842
+ }
843
+ params.push(param);
764
844
  }
765
845
  return params;
766
846
  }
767
847
 
848
+ function parseDefaultValue() {
849
+ const token = peek();
850
+ if (token.type === TOKEN.STRING) {
851
+ advance();
852
+ return { type: 'StringLiteral', value: token.value };
853
+ }
854
+ if (token.type === TOKEN.NUMBER) {
855
+ advance();
856
+ return { type: 'NumberLiteral', value: token.value };
857
+ }
858
+ if (token.type === TOKEN.TRUE_KW) {
859
+ advance();
860
+ return { type: 'BooleanLiteral', value: true };
861
+ }
862
+ if (token.type === TOKEN.FALSE_KW) {
863
+ advance();
864
+ return { type: 'BooleanLiteral', value: false };
865
+ }
866
+ if (token.type === TOKEN.NULL_KW) {
867
+ advance();
868
+ return { type: 'NullLiteral' };
869
+ }
870
+ return null;
871
+ }
872
+
768
873
  function parseGive() {
769
874
  consume(TOKEN.GIVE);
770
875
  const value = parseExpression();
771
876
  return { type: 'GiveStatement', value };
772
877
  }
773
878
 
879
+ // v1.0.0 — generators: `yield <expr>` (optionally bare `yield`).
880
+ function parseYield() {
881
+ consume(TOKEN.YIELD);
882
+ let value = null;
883
+ if (peek().type !== TOKEN.DONE && peek().type !== TOKEN.EOF) {
884
+ value = parseExpression();
885
+ }
886
+ return { type: 'YieldStatement', value };
887
+ }
888
+
889
+ // v1.0.0 — record kinds: `define a kind called "Person" with … done`
890
+ // The field block reuses the property-list grammar (`age is 0`), so each
891
+ // field gets a default expression just like an object literal.
892
+ function parseDefineKind() {
893
+ advance(); // define
894
+ const art = advance(); // "a" / "an"
895
+ // `define a kind called "Person"` — the word "kind" is optional prose.
896
+ if (peek().type === TOKEN.IDENTIFIER && peek().value === 'kind') {
897
+ advance(); // kind
898
+ } else if (peek().type === TOKEN.IDENTIFIER && peek().value === 'called') {
899
+ advance(); // (implicit 'kind' omitted)
900
+ } else {
901
+ throw new Error(makeError(
902
+ 'Expected "kind" (or "called") after "define a ' + art.value + '".\n\nExample:\n define a kind called "Person" with\n name is ""\n done',
903
+ peek()
904
+ ));
905
+ }
906
+ const called = peek();
907
+ if (called.type !== TOKEN.IDENTIFIER || called.value !== 'called') {
908
+ throw new Error(makeError(
909
+ 'Expected "called" after "define a kind".\n\nExample:\n define a kind called "Person" with\n name is ""\n done',
910
+ called
911
+ ));
912
+ }
913
+ advance(); // called
914
+ let name;
915
+ if (peek().type === TOKEN.STRING) {
916
+ name = advance().value;
917
+ } else {
918
+ const t = consume(TOKEN.IDENTIFIER, 'Expected a kind name after "kind called".');
919
+ name = t.value;
920
+ }
921
+ consume(TOKEN.WITH, 'Expected "with" after the kind name.\n\nExample:\n define a kind called "Person" with\n name is ""\n done');
922
+ const fields = parsePropertyList('kind "' + name + '" definition');
923
+ return { type: 'DefineKindStatement', name, fields };
924
+ }
925
+
926
+ // v1.0.0 — record constructor (expression): `create a Person with name "Ada" and age 17`
927
+ function parseCreateKind() {
928
+ advance(); // create
929
+ advance(); // a / an
930
+ const kind = consume(TOKEN.IDENTIFIER, 'Expected a kind name after "create a".').value;
931
+ consume(TOKEN.WITH, 'Expected "with" after the kind name.\n\nExample:\n create a Person with name "Ada" and age 17');
932
+ const pairs = [];
933
+ while (true) {
934
+ const key = consume(TOKEN.IDENTIFIER, 'Expected a field name in "create a ' + kind + ' with ...".').value;
935
+ const value = parsePrimary();
936
+ pairs.push({ key, value });
937
+ if (peek().type === TOKEN.AND) {
938
+ advance();
939
+ continue;
940
+ }
941
+ break;
942
+ }
943
+ return { type: 'CreateKindExpression', kind, pairs };
944
+ }
945
+
946
+ // v1.0.0 — native test DSL: `test "name" … done`
947
+ function parseTestStatement() {
948
+ advance(); // test
949
+ const name = consume(TOKEN.STRING, 'Expected a test name string after "test".').value;
950
+ const body = parseBody('"test" block');
951
+ return { type: 'TestStatement', name, body };
952
+ }
953
+
954
+ // v1.0.0 — assertions: `check <a> (equals|is|contains|raises) <b>`
955
+ function parseCheckStatement() {
956
+ advance(); // check
957
+ const a = parseExpression();
958
+ const opToken = peek();
959
+ if (!['equals', 'is', 'contains', 'raises'].includes(opToken.value)) {
960
+ throw new Error(makeError(
961
+ 'Expected "equals", "is", "contains" or "raises" after the value in a "check".\n\nExample:\n check score equals 42',
962
+ opToken
963
+ ));
964
+ }
965
+ const op = advance().value;
966
+ const b = parseExpression();
967
+ return { type: 'CheckStatement', a, op, b };
968
+ }
969
+
774
970
  // for each <item> in <collection> ... done
775
971
  // for every <item> in <collection> ... done (alias — "every" maps to EACH token)
776
972
  function parseForEach() {
@@ -792,12 +988,12 @@ function parse(tokens) {
792
988
  return { type: 'WhileStatement', condition, body };
793
989
  }
794
990
 
795
- // import "./file.pln"
991
+ // import "./file.ps"
796
992
  function parseImport() {
797
993
  consume(TOKEN.IMPORT);
798
994
  const filePath = consume(
799
995
  TOKEN.STRING,
800
- 'Expected a file path string after "import".\n\nExample:\n import "./math.pln"'
996
+ 'Expected a file path string after "import".\n\nExample:\n import "./math.ps"'
801
997
  ).value;
802
998
  return { type: 'ImportStatement', path: filePath };
803
999
  }
@@ -850,6 +1046,22 @@ function parse(tokens) {
850
1046
  return { type: 'NotFoundStatement', body };
851
1047
  }
852
1048
 
1049
+ // IOPL-native — "when \"event\" happens as data … done": event listener.
1050
+ // Must be checked before the "when someone" path.
1051
+ if (peek().type === TOKEN.STRING &&
1052
+ peekAt(1).type === TOKEN.HAPPENS) {
1053
+ const eventStr = advance().value;
1054
+ advance(); // happens
1055
+ let paramName = null;
1056
+ if (peek().type === TOKEN.AS) {
1057
+ advance(); // as
1058
+ paramName = consume(TOKEN.IDENTIFIER,
1059
+ 'Expected a parameter name after "as".\n\nExample:\n when "data.received" happens as data').value;
1060
+ }
1061
+ const body = parseBody('"when happens" block');
1062
+ return { type: 'WhenHappensStatement', event: eventStr, paramName, body };
1063
+ }
1064
+
853
1065
  // v2.1.0 — socket handlers inside a "websocket server" block come first:
854
1066
  // they read "when socket …", not "when someone …".
855
1067
  const whenToken = peek();
@@ -1173,7 +1385,7 @@ function parse(tokens) {
1173
1385
 
1174
1386
  // ── v2.1.1 — error handling, retries and backend middleware ───────────────
1175
1387
 
1176
- // try … [recover [as <name>]] … done
1388
+ // try … [recover [when <err> catches "<ErrorType>"]] … done
1177
1389
  function parseTryStatement() {
1178
1390
  advance(); // try
1179
1391
  const tryBody = [];
@@ -1188,17 +1400,34 @@ function parse(tokens) {
1188
1400
  const stmt = parseStatement();
1189
1401
  if (stmt) tryBody.push(stmt);
1190
1402
  }
1191
- let catchName = null;
1192
- let recoverBody = null;
1193
- if (peek().type !== TOKEN.DONE) {
1403
+ const catches = [];
1404
+ while (peek().type !== TOKEN.DONE) {
1405
+ if (peek().type === TOKEN.EOF) {
1406
+ throw new Error(makeError(
1407
+ 'Expected keyword "done" to close the "try" block before end of file.',
1408
+ peek()
1409
+ ));
1410
+ }
1194
1411
  advance(); // recover
1412
+ let paramName = null;
1413
+ let errorType = null;
1195
1414
  if (peek().type === TOKEN.AS) {
1196
- advance();
1197
- catchName = consume(TOKEN.IDENTIFIER,
1415
+ advance(); // as
1416
+ paramName = consume(TOKEN.IDENTIFIER,
1198
1417
  'Expected a variable name after "recover as".\n\nExample:\n recover as error').value;
1418
+ } else if (peek().type === TOKEN.WHEN) {
1419
+ advance(); // when
1420
+ paramName = consume(TOKEN.IDENTIFIER,
1421
+ 'Expected a variable name after "when" in recover.\n\nExample:\n recover when err catches "TypeError"').value;
1422
+ if (peek().type === TOKEN.CATCHES) {
1423
+ advance(); // catches
1424
+ errorType = consume(TOKEN.STRING,
1425
+ 'Expected an error type string after "catches".\n\nExample:\n recover when err catches "TypeError"').value;
1426
+ }
1199
1427
  }
1200
- recoverBody = [];
1201
- while (peek().type !== TOKEN.DONE) {
1428
+ const recoverBody = [];
1429
+ while (peek().type !== TOKEN.DONE &&
1430
+ !(peek().type === TOKEN.IDENTIFIER && peek().value === 'recover')) {
1202
1431
  if (peek().type === TOKEN.EOF) {
1203
1432
  throw new Error(makeError(
1204
1433
  'Expected keyword "done" to close the "recover" block before end of file.',
@@ -1208,9 +1437,10 @@ function parse(tokens) {
1208
1437
  const stmt = parseStatement();
1209
1438
  if (stmt) recoverBody.push(stmt);
1210
1439
  }
1440
+ catches.push({ param: paramName, errorType, body: recoverBody });
1211
1441
  }
1212
1442
  advance(); // done
1213
- return { type: 'TryStatement', tryBody, catchName, recoverBody };
1443
+ return { type: 'TryStatement', body: tryBody, catches };
1214
1444
  }
1215
1445
 
1216
1446
  // retry <n> times [every <n> seconds] … done
@@ -1438,17 +1668,25 @@ function parse(tokens) {
1438
1668
 
1439
1669
  let alternate = null;
1440
1670
  if (peek().type === TOKEN.OTHERWISE) {
1671
+ // `otherwise if` is an else-if chain (sharing one `done`) ONLY when `if`
1672
+ // sits on the same line as `otherwise`; a newline-separated `if` is a
1673
+ // nested if statement with its own `done`.
1674
+ const otherwiseLine = peek().line;
1441
1675
  advance();
1442
- alternate = [];
1443
- while (peek().type !== TOKEN.DONE) {
1444
- if (peek().type === TOKEN.EOF) {
1445
- throw new Error(makeError(
1446
- 'Expected keyword "done" before end of file to close the "otherwise" block.',
1447
- peek()
1448
- ));
1676
+ if (peek().type === TOKEN.IF && peek().line === otherwiseLine) {
1677
+ alternate = [parseElseIfChain()];
1678
+ } else {
1679
+ alternate = [];
1680
+ while (peek().type !== TOKEN.DONE) {
1681
+ if (peek().type === TOKEN.EOF) {
1682
+ throw new Error(makeError(
1683
+ 'Expected keyword "done" before end of file to close the "otherwise" block.',
1684
+ peek()
1685
+ ));
1686
+ }
1687
+ const stmt = parseStatement();
1688
+ if (stmt) alternate.push(stmt);
1449
1689
  }
1450
- const stmt = parseStatement();
1451
- if (stmt) alternate.push(stmt);
1452
1690
  }
1453
1691
  }
1454
1692
 
@@ -1456,6 +1694,50 @@ function parse(tokens) {
1456
1694
  return { type: 'IfStatement', condition, consequent, alternate };
1457
1695
  }
1458
1696
 
1697
+ // `otherwise if <condition> ... [otherwise if ...] [otherwise ...] done`
1698
+ // Parses a single else-if branch; a following `otherwise if` recurses, and a
1699
+ // trailing `otherwise` supplies the final else. The trailing `done` belongs to
1700
+ // the outermost `if` and is consumed there, not here.
1701
+ function parseElseIfChain() {
1702
+ advance(); // consume IF
1703
+ const condition = parseCondition();
1704
+
1705
+ const consequent = [];
1706
+ while (peek().type !== TOKEN.OTHERWISE && peek().type !== TOKEN.DONE) {
1707
+ if (peek().type === TOKEN.EOF) {
1708
+ throw new Error(makeError(
1709
+ 'Expected keyword "done" before end of file to close the "otherwise if" block.',
1710
+ peek()
1711
+ ));
1712
+ }
1713
+ const stmt = parseStatement();
1714
+ if (stmt) consequent.push(stmt);
1715
+ }
1716
+
1717
+ let alternate = null;
1718
+ if (peek().type === TOKEN.OTHERWISE) {
1719
+ const otherwiseLine = peek().line;
1720
+ advance();
1721
+ if (peek().type === TOKEN.IF && peek().line === otherwiseLine) {
1722
+ alternate = [parseElseIfChain()];
1723
+ } else {
1724
+ alternate = [];
1725
+ while (peek().type !== TOKEN.DONE) {
1726
+ if (peek().type === TOKEN.EOF) {
1727
+ throw new Error(makeError(
1728
+ 'Expected keyword "done" before end of file to close the "otherwise" block.',
1729
+ peek()
1730
+ ));
1731
+ }
1732
+ const stmt = parseStatement();
1733
+ if (stmt) alternate.push(stmt);
1734
+ }
1735
+ }
1736
+ }
1737
+
1738
+ return { type: 'IfStatement', condition, consequent, alternate };
1739
+ }
1740
+
1459
1741
  // ── Shared helpers ──────────────────────────────────────────────────────────
1460
1742
 
1461
1743
  function parseBody(context) {
@@ -1525,6 +1807,41 @@ function parse(tokens) {
1525
1807
 
1526
1808
  // primary → itemExpr | atom (postfix)*
1527
1809
  function parsePrimary() {
1810
+ // v1.0.0 — record constructor: `create a Person with name "Ada" and age 17`.
1811
+ // `create` then an article ("a"/"an") then a kind name then "with" pairs.
1812
+ if (peek().type === TOKEN.IDENTIFIER && peek().value === 'create') {
1813
+ const a1 = peekAt(1);
1814
+ const a2 = peekAt(2);
1815
+ const a3 = peekAt(3);
1816
+ if (a1.type === TOKEN.IDENTIFIER &&
1817
+ (a1.value === 'a' || a1.value === 'an') &&
1818
+ a2.type === TOKEN.IDENTIFIER &&
1819
+ (a3.value === 'with')) {
1820
+ return parseCreateKind();
1821
+ }
1822
+ }
1823
+
1824
+ // v1.0.0 — concurrency combinators: `all of [a(), b()]`, `any of [...]`,
1825
+ // `settled of [...]`. Guard on the identifier + "of" lookahead so plain
1826
+ // property reads like `all of the_list` still work as well as prose.
1827
+ if (peek().type === TOKEN.IDENTIFIER &&
1828
+ (peek().value === 'all' || peek().value === 'any' || peek().value === 'settled') &&
1829
+ peekAt(1).type === TOKEN.IDENTIFIER && peekAt(1).value === 'of') {
1830
+ const comboKw = advance().value; // all | any | settled
1831
+ advance(); // of
1832
+ const items = parseExpression();
1833
+ return { type: 'ConcurrencyExpression', combo: comboKw, items };
1834
+ }
1835
+
1836
+ // v1.0.0 — `spread of <collection>` unfolds an iterable into a new array.
1837
+ if (peek().type === TOKEN.IDENTIFIER && peek().value === 'spread' &&
1838
+ peekAt(1).type === TOKEN.IDENTIFIER && peekAt(1).value === 'of') {
1839
+ advance(); // spread
1840
+ advance(); // of
1841
+ const collection = parsePrimary();
1842
+ return { type: 'SpreadExpression', collection };
1843
+ }
1844
+
1528
1845
  const item = tryParseItemExpression();
1529
1846
  if (item) return item;
1530
1847
  let node = parseAtom();
@@ -2000,6 +2317,215 @@ function parse(tokens) {
2000
2317
  return cleaned;
2001
2318
  }
2002
2319
 
2320
+ // ── IOPL-native features ──────────────────────────────────────────────────
2321
+
2322
+ // gather each item in list giving expr
2323
+ function parseGatherStatement() {
2324
+ advance(); // gather
2325
+ consume(TOKEN.EACH,
2326
+ 'Expected "each" after "gather".\n\nExample:\n gather each item in names giving item + "!"');
2327
+ const item = consume(TOKEN.IDENTIFIER,
2328
+ 'Expected an item name after "each".').value;
2329
+ consume(TOKEN.IN,
2330
+ `Expected "in" after "${item}".\n\nExample:\n gather each item in names giving item + "!"`);
2331
+ const collection = parseExpression();
2332
+ if (peek().type === TOKEN.IDENTIFIER && peek().value === 'giving') {
2333
+ advance(); // giving
2334
+ } else {
2335
+ throw new Error(makeError(
2336
+ 'Expected "giving" after the collection expression.\n\nExample:\n gather each item in names giving item + "!"',
2337
+ peek()
2338
+ ));
2339
+ }
2340
+ const body = parseExpression();
2341
+ return { type: 'GatherStatement', item, collection, body };
2342
+ }
2343
+
2344
+ // filter each item in list when condition
2345
+ function parseFilterStatement() {
2346
+ advance(); // filter
2347
+ consume(TOKEN.EACH,
2348
+ 'Expected "each" after "filter".\n\nExample:\n filter each item in numbers when item is above 5');
2349
+ const item = consume(TOKEN.IDENTIFIER,
2350
+ 'Expected an item name after "each".').value;
2351
+ consume(TOKEN.IN,
2352
+ `Expected "in" after "${item}".\n\nExample:\n filter each item in numbers when item is above 5`);
2353
+ const collection = parseExpression();
2354
+ if (peek().type === TOKEN.WHEN ||
2355
+ (peek().type === TOKEN.IDENTIFIER && peek().value === 'when')) {
2356
+ advance(); // when
2357
+ } else {
2358
+ throw new Error(makeError(
2359
+ 'Expected "when" after the collection expression.\n\nExample:\n filter each item in numbers when item is above 5',
2360
+ peek()
2361
+ ));
2362
+ }
2363
+ const condition = parseAndCondition();
2364
+ return { type: 'FilterStatement', item, collection, condition };
2365
+ }
2366
+
2367
+ // total each item in list giving expr
2368
+ function parseTotalStatement() {
2369
+ advance(); // total
2370
+ consume(TOKEN.EACH,
2371
+ 'Expected "each" after "total".\n\nExample:\n total each item in numbers giving running + item');
2372
+ const item = consume(TOKEN.IDENTIFIER,
2373
+ 'Expected an item name after "each".').value;
2374
+ consume(TOKEN.IN,
2375
+ `Expected "in" after "${item}".\n\nExample:\n total each item in numbers giving running + item`);
2376
+ const collection = parseExpression();
2377
+ if (peek().type === TOKEN.IDENTIFIER && peek().value === 'giving') {
2378
+ advance(); // giving
2379
+ } else {
2380
+ throw new Error(makeError(
2381
+ 'Expected "giving" after the collection expression.\n\nExample:\n total each item in numbers giving running + item',
2382
+ peek()
2383
+ ));
2384
+ }
2385
+ const body = parseExpression();
2386
+ return { type: 'TotalStatement', item, collection, body };
2387
+ }
2388
+
2389
+ // match <expr> against ... done
2390
+ // "case1" → show "one"
2391
+ // "case2" → show "two"
2392
+ // otherwise → show "other"
2393
+ // match pattern "regex" in text as name
2394
+ function parseMatchStatement() {
2395
+ advance(); // match
2396
+
2397
+ // Regex match form: match pattern "regex" in text as name
2398
+ if (peek().type === TOKEN.PATTERN_KW) {
2399
+ advance(); // pattern
2400
+ const pattern = consume(TOKEN.STRING,
2401
+ 'Expected a regex pattern string after "pattern".\n\nExample:\n match pattern "^(\\d+)$" in text as result').value;
2402
+ const inToken = peek();
2403
+ if (inToken.type !== TOKEN.IN) {
2404
+ throw new Error(makeError(
2405
+ 'Expected "in" after the pattern string.\n\nExample:\n match pattern "^(\\d+)$" in text as result',
2406
+ inToken
2407
+ ));
2408
+ }
2409
+ advance(); // in
2410
+ const source = parseExpression();
2411
+ const asToken = peek();
2412
+ if (asToken.type !== TOKEN.AS) {
2413
+ throw new Error(makeError(
2414
+ 'Expected "as" after the source expression.\n\nExample:\n match pattern "^(\\d+)$" in text as result',
2415
+ asToken
2416
+ ));
2417
+ }
2418
+ advance(); // as
2419
+ const name = consume(TOKEN.IDENTIFIER,
2420
+ 'Expected a variable name after "as".\n\nExample:\n match pattern "^(\\d+)$" in text as result').value;
2421
+ return { type: 'RegexMatchStatement', pattern, source, name };
2422
+ }
2423
+
2424
+ // Pattern matching form: match expr against ... done
2425
+ const value = parseExpression();
2426
+ consume(TOKEN.AGAINST,
2427
+ 'Expected "after" the expression.\n\nExample:\n match color against\n "red" → show "stop"\n done');
2428
+ const cases = [];
2429
+ let defaultCase = null;
2430
+ while (peek().type !== TOKEN.DONE) {
2431
+ if (peek().type === TOKEN.EOF) {
2432
+ throw new Error(makeError(
2433
+ 'Expected keyword "done" to close the "match" block before end of file.',
2434
+ peek()
2435
+ ));
2436
+ }
2437
+ // otherwise → body
2438
+ if (peek().type === TOKEN.OTHERWISE) {
2439
+ advance(); // otherwise
2440
+ consume(TOKEN.ARROW,
2441
+ 'Expected "->" after "otherwise".\n\nExample:\n otherwise → show "other"');
2442
+ defaultCase = [];
2443
+ while (peek().type !== TOKEN.DONE) {
2444
+ if (peek().type === TOKEN.EOF) {
2445
+ throw new Error(makeError(
2446
+ 'Expected keyword "done" to close the "match" block before end of file.',
2447
+ peek()
2448
+ ));
2449
+ }
2450
+ const stmt = parseStatement();
2451
+ if (stmt) defaultCase.push(stmt);
2452
+ }
2453
+ break;
2454
+ }
2455
+ const test = parseExpression();
2456
+ consume(TOKEN.ARROW,
2457
+ 'Expected "->" after the case expression.\n\nExample:\n "red" → show "stop"');
2458
+ const caseBody = [];
2459
+ while (peek().type !== TOKEN.DONE && peek().type !== TOKEN.OTHERWISE &&
2460
+ !(peek().type === TOKEN.STRING || peek().type === TOKEN.NUMBER ||
2461
+ peek().type === TOKEN.TRUE_KW || peek().type === TOKEN.FALSE_KW ||
2462
+ peek().type === TOKEN.NULL_KW)) {
2463
+ if (peek().type === TOKEN.EOF) {
2464
+ throw new Error(makeError(
2465
+ 'Expected keyword "done" to close the "match" block before end of file.',
2466
+ peek()
2467
+ ));
2468
+ }
2469
+ const stmt = parseStatement();
2470
+ if (stmt) caseBody.push(stmt);
2471
+ }
2472
+ cases.push({ test, body: caseBody });
2473
+ }
2474
+ advance(); // done
2475
+ return { type: 'MatchStatement', value, cases, defaultCase };
2476
+ }
2477
+
2478
+ // emit "event.name" with data
2479
+ function parseEmitStatement() {
2480
+ advance(); // emit
2481
+ const eventToken = peek();
2482
+ const event = consume(TOKEN.STRING,
2483
+ 'Expected an event name string after "emit".\n\nExample:\n emit "data.received" with payload').value;
2484
+ const withToken = peek();
2485
+ if (withToken.type !== TOKEN.WITH) {
2486
+ throw new Error(makeError(
2487
+ 'Expected "with" after the event name.\n\nExample:\n emit "data.received" with payload',
2488
+ withToken
2489
+ ));
2490
+ }
2491
+ advance(); // with
2492
+ const data = parseExpression();
2493
+ return { type: 'EmitStatement', event, data };
2494
+ }
2495
+
2496
+ // stream "file.txt" as line ... done
2497
+ function parseStreamStatement() {
2498
+ advance(); // stream
2499
+ const filename = parseExpression();
2500
+ const asToken = peek();
2501
+ if (asToken.type !== TOKEN.AS) {
2502
+ throw new Error(makeError(
2503
+ 'Expected "as" after the filename.\n\nExample:\n stream "data.txt" as line\n show line\n done',
2504
+ asToken
2505
+ ));
2506
+ }
2507
+ advance(); // as
2508
+ const paramName = consume(TOKEN.IDENTIFIER,
2509
+ 'Expected a variable name after "as".\n\nExample:\n stream "data.txt" as line').value;
2510
+ const body = parseBody('"stream" block');
2511
+ return { type: 'StreamStatement', filename, paramName, body };
2512
+ }
2513
+
2514
+ // run in parallel ... done as results
2515
+ function parseRunParallelStatement() {
2516
+ advance(); // run (already checked by caller)
2517
+ advance(); // in
2518
+ advance(); // parallel
2519
+ const body = parseBody('"run in parallel" block');
2520
+ let resultName = null;
2521
+ if (peek().type === TOKEN.AS) {
2522
+ advance(); // as
2523
+ resultName = consume(TOKEN.IDENTIFIER,
2524
+ 'Expected a variable name after "as".\n\nExample:\n run in parallel\n remember a as wait for slowJob()\n done as results').value;
2525
+ }
2526
+ return { type: 'RunParallelStatement', body, resultName };
2527
+ }
2528
+
2003
2529
  // name(arg, arg, ...)
2004
2530
  // name(value to collection) → v1.1 collection/io forms (add, remove, write)
2005
2531
  function parseCallExpression() {