plainscript-lang 1.0.0 → 1.0.2

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 (52) hide show
  1. package/README.md +157 -150
  2. package/compiler/bundler.js +2 -2
  3. package/compiler/cli.js +172 -65
  4. package/compiler/formatter.js +1 -1
  5. package/compiler/generator.js +905 -184
  6. package/compiler/lexer.js +128 -54
  7. package/compiler/parser.js +1075 -155
  8. package/compiler/version.js +1 -1
  9. package/docs/CAPABILITY_GAP_AUDIT.md +131 -30
  10. package/docs/PLAINSCRIPT-SPEC.md +584 -0
  11. package/docs/index.html +48 -52
  12. package/docs/website/script.js +110 -24
  13. package/docs/website/style.css +4 -4
  14. package/examples/arrays.pln +12 -0
  15. package/examples/{auth-api.ps → auth-api.pln} +3 -3
  16. package/examples/{cache-and-jobs.ps → cache-and-jobs.pln} +1 -1
  17. package/examples/{concurrency.ps → concurrency.pln} +8 -8
  18. package/examples/{database.ps → database.pln} +1 -1
  19. package/examples/{deployment.ps → deployment.pln} +2 -2
  20. package/examples/{email-send.ps → email-send.pln} +1 -1
  21. package/examples/{error-handling.ps → error-handling.pln} +8 -7
  22. package/examples/{expressions.ps → expressions.pln} +1 -1
  23. package/examples/{file-uploads.ps → file-uploads.pln} +4 -4
  24. package/examples/{files-and-config.ps → files-and-config.pln} +4 -4
  25. package/examples/football-backend/{app.ps → app.pln} +2 -2
  26. package/examples/{http-client.ps → http-client.pln} +18 -18
  27. package/examples/id-verification/{app.ps → app.pln} +1 -1
  28. package/examples/{loops.ps → loops.pln} +2 -3
  29. package/examples/modules/{app.ps → app.pln} +4 -4
  30. package/examples/modules/{math.ps → math.pln} +1 -1
  31. package/examples/{record-kinds.ps → record-kinds.pln} +4 -4
  32. package/examples/{rest-api-fetch.ps → rest-api-fetch.pln} +1 -1
  33. package/examples/{rest-api.ps → rest-api.pln} +5 -5
  34. package/examples/{scheduled-tasks.ps → scheduled-tasks.pln} +2 -2
  35. package/examples/{search-and-filter.ps → search-and-filter.pln} +5 -5
  36. package/examples/{sessions-and-cookies.ps → sessions-and-cookies.pln} +2 -2
  37. package/examples/start.pln +2 -0
  38. package/examples/{stdlib.ps → stdlib.pln} +2 -2
  39. package/examples/{telegram-bot.ps → telegram-bot.pln} +2 -2
  40. package/examples/{websocket-server.ps → websocket-server.pln} +1 -1
  41. package/package.json +2 -2
  42. package/docs/PLINJS_SPEC.md +0 -1151
  43. package/examples/arrays.ps +0 -13
  44. package/examples/start.ps +0 -2
  45. /package/examples/{day2.ps → day2.pln} +0 -0
  46. /package/examples/{day3.ps → day3.pln} +0 -0
  47. /package/examples/{hello.ps → hello.pln} +0 -0
  48. /package/examples/{objects.ps → objects.pln} +0 -0
  49. /package/examples/{server.ps → server.pln} +0 -0
  50. /package/examples/{web-app.ps → web-app.pln} +0 -0
  51. /package/examples/whatsapp-bot/{pairing.ps → pairing.pln} +0 -0
  52. /package/examples/whatsapp-bot/{qr.ps → qr.pln} +0 -0
package/README.md CHANGED
@@ -1,7 +1,11 @@
1
1
  # PlainScript
2
2
 
3
+ [![CI](https://github.com/ayoistooslick/plainscript/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/ayoistooslick/plainscript/actions/workflows/npm-publish.yml)
4
+ [![npm version](https://badge.fury.io/js/plainscript-lang.svg?icon=si%3Anpm)](https://www.npmjs.com/package/plainscript-lang)
5
+ [![Downloads](https://img.shields.io/badge/downloads-1.1GB/month-green)](https://www.npmjs.com/package/plainscript-lang)
6
+
3
7
  <p align="center">
4
- <img src="docs/logo.jpg" alt="PlainScript Logo" width="200" />
8
+ <img src="https://github.com/ayoistooslick/plainscript/blob/main/docs/logo.jpg" alt="PlainScript Logo" width="200" />
5
9
  </p>
6
10
 
7
11
  > "When even a simple sentence can be code."
@@ -9,14 +13,14 @@
9
13
 
10
14
  PlainScript is an Intent-Oriented Programming Language (IOPL). You describe **what** you want; the compiler decides **how** to implement it in JavaScript.
11
15
 
12
- **Current version:** v1.0.0 — the `plainscript` npm package with a TypeScript-style production build (`plainscript build` → `dist/`, source names preserved).
16
+ **Current version:** v1.0.2 — the `plainscript` npm package with a TypeScript-style production build (`plainscript build` → `dist/`, source names preserved).
13
17
 
14
18
  ---
15
19
 
16
20
  ## Quick start
17
21
 
18
22
  ```bash
19
- npx plainscript new myapp # scaffolds src/app.ps and package.json
23
+ npx plainscript new myapp # scaffolds src/app.pln and package.json
20
24
  cd myapp
21
25
  npm install # installs plainscript as a devDependency plus runtime packages
22
26
  npm run build # compiles src/ -> dist/ (plainscript build)
@@ -26,8 +30,8 @@ node dist/app.js # or: npm start
26
30
  Adding PlainScript to an existing project:
27
31
 
28
32
  ```bash
29
- npm install --save-dev plainscript
30
- # start writing src/*.ps files — plainscript build auto-discovers them
33
+ npm install --save-dev plainscript-lang
34
+ # start writing src/*.pln files — plainscript build auto-discovers them
31
35
  ```
32
36
 
33
37
  No global install is needed anywhere — everything runs through npm scripts
@@ -38,17 +42,17 @@ and `npx`.
38
42
  ## CLI
39
43
 
40
44
  ```
41
- plainscript run <file.ps> Install missing dependencies, compile and execute
45
+ plainscript run <file.pln> Install missing dependencies, compile and execute
42
46
  (executes from a scratch dir — nothing is written
43
47
  into your project)
44
- plainscript build [file.ps] Compile to dist/. With no argument, builds every
45
- .ps file under the source root, preserving names
48
+ plainscript build [file.pln] Compile to dist/. With no argument, builds every
49
+ .pln file under the source root, preserving names
46
50
  and folder structure
47
- plainscript check <file.ps> Check syntax only (no output, no execution)
48
- plainscript fmt <file.ps> Format a PlainScript file in-place
51
+ plainscript check <file.pln> Check syntax only (no output, no execution)
52
+ plainscript fmt <file.pln> Format a PlainScript file in-place
49
53
  plainscript new [name] Create a new PlainScript project (npm-ready)
50
54
  plainscript install Install dependencies detected in the project's sources
51
- plainscript start Build src/app.ps and run its dist/ output
55
+ plainscript start Build src/app.pln and run its dist/ output
52
56
  plainscript doctor Check the PlainScript project environment
53
57
  plainscript add <package> Install a package into the project
54
58
  plainscript remove <package> Uninstall a package from the project
@@ -62,13 +66,13 @@ plainscript help Print help text
62
66
  ## Building and configuration
63
67
 
64
68
  `plainscript build` is a deterministic production build, TypeScript-style but for
65
- `.ps` sources — **zero configuration required**:
69
+ `.pln` sources — **zero configuration required**:
66
70
 
67
- - `plainscript build` (no argument) discovers every `.ps` file under `src/` and
71
+ - `plainscript build` (no argument) discovers every `.pln` file under `src/` and
68
72
  compiles each to `dist/` **preserving source file names and folder structure**:
69
- `src/messi.ps` → `dist/messi.js`,
70
- `src/helpers/math.ps` → `dist/helpers/math.js`.
71
- - `plainscript build <file.ps>` compiles a single file into `dist/`.
73
+ `src/messi.pln` → `dist/messi.js`,
74
+ `src/helpers/math.pln` → `dist/helpers/math.js`.
75
+ - `plainscript build <file.pln>` compiles a single file into `dist/`.
72
76
  - Imports are bundled into each output, so every file in `dist/` runs
73
77
  standalone under Node.
74
78
  - Rebuilds are byte-identical — safe to commit, diff, and cache.
@@ -92,12 +96,6 @@ For projects that need custom output or source directories, add a
92
96
  }
93
97
  ```
94
98
 
95
- | Key | Default | Meaning |
96
- |-------------|----------------------------------|----------------------------------------------|
97
- | `outDir` | `"dist"` | Build output directory |
98
- | `rootDir` | `"src"` if it exists, else `"."` | Root that `plainscript build` scans for sources |
99
- | `exclude` | `["node_modules"]` | Directories to skip during source discovery |
100
-
101
99
  ### Publishing a library written in PlainScript
102
100
 
103
101
  ```json
@@ -108,11 +106,11 @@ For projects that need custom output or source directories, add a
108
106
  "build": "plainscript build",
109
107
  "prepare": "plainscript build"
110
108
  },
111
- "devDependencies": { "plainscript": "^1.0.0" }
109
+ "devDependencies": { "plainscript-lang": "^1.0.2" }
112
110
  }
113
111
  ```
114
112
 
115
- `src/index.ps` builds to `dist/index.js`; consumers install and `require()`
113
+ `src/index.pln` builds to `dist/index.js`; consumers install and `require()`
116
114
  it like any Node package. There is no PlainScript-specific registry or format —
117
115
  standard `package.json` semantics apply.
118
116
 
@@ -123,9 +121,9 @@ standard `package.json` semantics apply.
123
121
  ### Variables
124
122
 
125
123
  ```plainscript
126
- remember name as "Ayokunle"
127
- remember age as 16
128
- age becomes 17
124
+ let name be "Ayokunle"
125
+ let age be 16
126
+ set age to 17
129
127
  ```
130
128
 
131
129
  ### String Templates
@@ -133,11 +131,11 @@ age becomes 17
133
131
  Backtick-delimited strings preserve whitespace and support `${expression}` interpolation:
134
132
 
135
133
  ```plainscript
136
- remember name as "World"
137
- remember greeting as `Hello ${name}!`
134
+ let name be "World"
135
+ let greeting be `Hello ${name}!`
138
136
  show greeting
139
137
 
140
- remember email as `Dear ${customer},
138
+ let email be `Dear ${customer},
141
139
 
142
140
  Thank you for your order #${orderId}.
143
141
 
@@ -150,57 +148,72 @@ Interpolation compiles directly to JavaScript template literals — it is not ev
150
148
  ### Conditions
151
149
 
152
150
  ```plainscript
153
- if age is at least 18
151
+ when age is at least 18
154
152
  show "Adult"
155
153
  otherwise
156
154
  show "Teenager"
157
155
  done
158
156
 
159
- if name contains "PlainScript"
157
+ when name contains "PlainScript"
160
158
  show "Found it"
161
159
  done
162
160
 
163
- if score between 90 and 100
161
+ when score between 90 and 100
164
162
  show "A grade"
165
163
  done
166
164
  ```
167
165
 
166
+ English alternatives: `same as` (`===`), `different from` (`!==`), `more than` (`>`), `fewer than` (`<`).
167
+
168
168
  All comparison operators:
169
169
 
170
170
  | PlainScript | JavaScript |
171
171
  |------------------------|--------------------|
172
172
  | `is` / `is equal to` | `===` |
173
+ | `same as` | `===` |
173
174
  | `is not` | `!==` |
175
+ | `different from` | `!==` |
174
176
  | `is greater than` / `is above` | `>` |
177
+ | `more than` | `>` |
175
178
  | `is less than` / `is below` | `<` |
179
+ | `fewer than` | `<` |
176
180
  | `is at least` | `>=` |
177
181
  | `is at most` | `<=` |
178
182
  | `is empty` | `.length === 0` |
179
183
  | `is not empty` | `.length > 0` |
180
184
  | `contains "x"` | `.includes("x")` |
185
+ | `made of "x"` | `.includes("x")` |
181
186
  | `starts with "x"` | `.startsWith("x")` |
187
+ | `starts as "x"` | `.startsWith("x")` |
182
188
  | `ends with "x"` | `.endsWith("x")` |
189
+ | `ends as "x"` | `.endsWith("x")` |
183
190
  | `between A and B` | `>= A && <= B` |
191
+ | `has field "x"` | `"x" in obj` |
192
+ | `at position key` | `obj[key]` |
184
193
 
185
194
  ### Functions
186
195
 
187
196
  ```plainscript
188
- make add(a, b)
189
- give a + b
197
+ to add a and b together
198
+ give back a + b
190
199
  done
191
200
  show add(5, 7)
201
+
202
+ to multiply x and y together
203
+ give back x * y
204
+ done
192
205
  ```
193
206
 
194
207
  ### Arrays & Objects
195
208
 
196
209
  ```plainscript
197
- remember players as ["Haaland", "Foden", "Rodri"]
210
+ let players be list with "Haaland", "Foden", "Rodri"
198
211
  show players[0]
199
- players[1] becomes "Palmer"
212
+ set players[1] to "Palmer"
200
213
 
201
- remember user as
202
- name is "Ayokunle"
203
- age is 17
214
+ let user be record with
215
+ name "Ayokunle"
216
+ age 17
204
217
  done
205
218
  show user.name
206
219
  ```
@@ -217,7 +230,7 @@ for every item in basket // alias for "for each"
217
230
  done
218
231
 
219
232
  while age is less than 18
220
- age becomes age + 1
233
+ set age to age + 1
221
234
  done
222
235
  ```
223
236
 
@@ -228,12 +241,12 @@ Collections, properties, and files read like sentences.
228
241
  **Items**
229
242
 
230
243
  ```plainscript
231
- remember players as ["Haaland", "Foden", "Rodri"]
244
+ let players be list with "Haaland", "Foden", "Rodri"
232
245
 
233
246
  show first player from players // players[0]
234
247
  show last player from players // players[players.length - 1]
235
248
  show player two from players // players[1]
236
- first player from players becomes "Haaland" // players[0] = "Haaland"
249
+ first player from players is now "Haaland" // players[0] = "Haaland"
237
250
  ```
238
251
 
239
252
  Number words from `one` to `twenty` map to one-based positions: `player one` is the first item.
@@ -245,17 +258,19 @@ show players length // players.length
245
258
  add("Palmer" to players) // players.push("Palmer")
246
259
  remove("Rodri" from players) // players.splice(players.indexOf("Rodri"), 1)
247
260
 
248
- if players contains "Foden" // players.includes("Foden")
261
+ when players contains "Foden" // players.includes("Foden")
249
262
  show "Found"
250
263
  done
251
264
  ```
252
265
 
266
+ English alternatives: `made of` (`.includes()`), `starts as` (`.startsWith()`), `ends as` (`.endsWith()`), `has field` (`in`), `at position` (`[]`).
267
+
253
268
  **Properties**
254
269
 
255
270
  ```plainscript
256
271
  show name of user // user.name
257
272
  show city of address of customer // customer.address.city
258
- name of user becomes "Ayo" // user.name = "Ayo"
273
+ name of user is now "Ayo" // user.name = "Ayo"
259
274
  ```
260
275
 
261
276
  `of` chains right-to-left: `city of address of customer` reads the city of the address of the customer.
@@ -263,51 +278,35 @@ name of user becomes "Ayo" // user.name = "Ayo"
263
278
  **Files**
264
279
 
265
280
  ```plainscript
266
- remember data as read("users.txt") // fs.readFileSync("users.txt", 'utf8')
281
+ let data be read("users.txt") // fs.readFileSync("users.txt", 'utf8')
267
282
  write(data to "users.txt") // fs.writeFileSync(data, "users.txt", 'utf8')
268
283
  ```
269
284
 
270
285
  The older `readFile()` / `writeFile()` forms still work and are unchanged.
271
286
 
272
- ### JavaScript Gateway
273
-
274
- JavaScript blocks run raw JavaScript with full async support:
287
+ ### Logical Assignment
275
288
 
276
289
  ```plainscript
277
- remember response as javascript
278
- const res = await fetch("https://api.example.com")
279
- const data = await res.json()
280
- return data
281
- done
282
- show response
283
- ```
290
+ let flag be false
291
+ flag or is now true
292
+ show flag
284
293
 
285
- `ask` reads a line of input from the terminal:
286
-
287
- ```plainscript
288
- ask "What is your name?" as name
289
- show "Hello, " + name
294
+ let val be null
295
+ val nullish is now "default"
296
+ show val
290
297
  ```
291
298
 
292
- Any npm package can be declared with `use`:
299
+ ### TypeScript-parity capabilities (1.0.2)
293
300
 
294
- ```plainscript
295
- use axios
296
- use node-fetch
297
- use @scope/package-name
298
- ```
299
-
300
- ### TypeScript-parity capabilities (1.0.0)
301
-
302
- The full capability-gap audit lives in [`docs/CAPABILITY_GAP_AUDIT.md`](docs/CAPABILITY_GAP_AUDIT.md).
301
+ The full capability-gap audit lives in [`docs/CAPABILITY_GAP_AUDIT.md`](https://github.com/ayoistooslick/plainscript/blob/main/docs/CAPABILITY_GAP_AUDIT.md).
303
302
  These features close it in PlainScript's own grammar:
304
303
 
305
- - **Record kinds (classes):** `define a kind called "Person" with name is "" done`
304
+ - **Record kinds (classes):** `to define a kind called "Person" with name "" end`
306
305
  + `create a Person with name "Ada" and age 17`. Plain-object instances; unknown
307
306
  fields throw.
308
307
  - **Concurrency:** `all of [...]`, `any of [...]`, `settled of [...]`,
309
308
  `withTimeout(promise, ms)`.
310
- - **Generators:** `yield` inside `make ... done`; consumed with `for each` or
309
+ - **Generators:** `yield` inside `define ... end`; consumed with `for each` or
311
310
  `spread of`.
312
311
  - **Reflection:** `typeOf`, `fieldsOf`, `valueOf`, `hasField`, `sizeOf`.
313
312
  - **Binary:** `base64Encode/Decode`, `textToBytes/bytesToText`, `sha256/sha1/md5`.
@@ -318,7 +317,7 @@ These features close it in PlainScript's own grammar:
318
317
  - **Streams:** `writeLine`, `appendLine`.
319
318
  - **Collections:** `keyMap/mapSet/mapGet/mapHas/mapDelete`, `newSet/addToSet`.
320
319
  - **Dynamic modules:** `loadModule("./m")`.
321
- - **Native tests:** `test "name" ... done` with `check a equals b`,
320
+ - **Native tests:** `test "name" ... end` with `check a equals b`,
322
321
  `check a contains b`, `check a is b`, `check <expr> raises "msg"`.
323
322
  - **Exports:** `export <name>`.
324
323
 
@@ -351,14 +350,14 @@ so data survives restarts either way.
351
350
  ### HTTP client
352
351
 
353
352
  ```plainscript
354
- remember r as get "https://api.example.com/users"
355
- if ok of r
353
+ let r be get "https://api.example.com/users"
354
+ when ok of r
356
355
  show status of r
357
356
  show data of r
358
357
  done
359
358
 
360
- remember created as post url with body
361
- headers { accept: "application/json" }
359
+ let created be post url with body
360
+ headers record with accept "application/json" done
362
361
  timeout 5000
363
362
  ```
364
363
 
@@ -370,12 +369,12 @@ awaits raw promises when you need it.
370
369
  ### Passwords and tokens (built-in auth)
371
370
 
372
371
  ```plainscript
373
- remember hash as hashPassword("correct horse")
374
- if checkPassword(password of body of request, hash)
375
- remember token as createToken(user, env("TOKEN_SECRET"), 3600)
372
+ let hash be hashPassword("correct horse")
373
+ when checkPassword(password of body of request, hash)
374
+ let token be createToken(user, env("TOKEN_SECRET"), 3600)
376
375
  done
377
376
 
378
- remember payload as readToken(token, env("TOKEN_SECRET"))
377
+ let payload be readToken(token, env("TOKEN_SECRET"))
379
378
  ```
380
379
 
381
380
  `hashPassword`/`checkPassword` use scrypt; tokens are HMAC-signed with an
@@ -388,17 +387,17 @@ web app
388
387
  enable sessions "a-long-random-secret"
389
388
 
390
389
  route post "/login"
391
- user of session of request becomes username of body of request
392
- reply "welcome"
390
+ user of session of request is username of body of request
391
+ show "welcome"
393
392
  done
394
393
 
395
394
  route get "/me"
396
- reply user of session of request
395
+ show user of session of request
397
396
  done
398
397
 
399
398
  route post "/logout"
400
399
  destroy session
401
- reply "bye"
400
+ show "bye"
402
401
  done
403
402
  ```
404
403
 
@@ -408,12 +407,12 @@ in-memory: restarting the server signs everyone out.
408
407
  ### File uploads
409
408
 
410
409
  ```plainscript
411
- accept uploads limit "5 MB" allow ["image/png", "image/jpeg"] folder "uploads"
410
+ accept uploads limit "5 MB" allow list with "image/png", "image/jpeg" folder "uploads"
412
411
 
413
412
  route post "/scan"
414
- remember file as upload("doc")
413
+ let file be upload("doc")
415
414
  ocr path of file as text
416
- reply "scanned: " + text
415
+ show "scanned: " + text
417
416
  done
418
417
  ```
419
418
 
@@ -457,7 +456,7 @@ user and the browser lands on `landing`.
457
456
  ```plainscript
458
457
  when nothing matches
459
458
  status 404
460
- reply json
459
+ show json
461
460
  error is "No such road"
462
461
  done
463
462
  done
@@ -467,7 +466,7 @@ done
467
466
 
468
467
  ```plainscript
469
468
  try
470
- remember data as jsonDecode(raw)
469
+ let data be jsonDecode(raw)
471
470
  recover as err
472
471
  show "bad json: " + message of err
473
472
  done
@@ -485,7 +484,7 @@ No imports needed. These functions are built into the compiler:
485
484
 
486
485
  | PlainScript | Description |
487
486
  |--------------------------|------------------------------------|
488
- | `print(x)` | Print a value (`console.log`) |
487
+ | `show(x)` | Print a value (`console.log`) |
489
488
  | `readFile("path")` | Read a file as UTF-8 text |
490
489
  | `writeFile("path", data)` | Write text to a file |
491
490
  | `read("path")` | Read a file as UTF-8 text |
@@ -512,11 +511,11 @@ No imports needed. These functions are built into the compiler:
512
511
  web app
513
512
 
514
513
  route "/"
515
- reply "Hello from PlainScript!"
514
+ show "Hello from PlainScript!"
516
515
  done
517
516
 
518
517
  route "/api/status"
519
- reply json
518
+ show json
520
519
  status is "ok"
521
520
  version is "2.0"
522
521
  done
@@ -540,7 +539,7 @@ insert
540
539
  INSERT INTO users (name) VALUES ('Alice')
541
540
  done
542
541
 
543
- remember rows as query
542
+ let rows be query
544
543
  SELECT * FROM users
545
544
  done
546
545
  ```
@@ -561,19 +560,19 @@ allow cors
561
560
  group "/api"
562
561
 
563
562
  route get "/users"
564
- remember users as query
563
+ let users be query
565
564
  SELECT * FROM users
566
565
  done
567
- reply users
566
+ show users
568
567
  done
569
568
 
570
569
  route post "/users"
571
- remember missing as validate(body of request, ["name", "email"])
572
- if length(missing) is greater than 0
570
+ let missing be validate(body of request, list with "name", "email")
571
+ when length of missing is greater than 0
573
572
  status 400
574
- reply missing
573
+ show missing
575
574
  otherwise
576
- reply "created"
575
+ show "created"
577
576
  done
578
577
  done
579
578
 
@@ -631,7 +630,11 @@ schedule "0 2 * * *"
631
630
  show "nightly cleanup"
632
631
  done
633
632
 
634
- run background resizeImage("photo.png")
633
+ to resize name
634
+ show `resizing ${name}`
635
+ done
636
+
637
+ run background resize("photo.png")
635
638
  ```
636
639
 
637
640
  ### WebSocket servers
@@ -651,7 +654,7 @@ done
651
654
 
652
655
  ```plainscript
653
656
  cache env("REDIS_URL") // omit for an in-memory Map store with TTL
654
- remember token as cacheGet("token")
657
+ let token be cacheGet("token")
655
658
  cacheSet("greeting", "hi", 60)
656
659
  cacheDelete("greeting")
657
660
  ```
@@ -662,15 +665,15 @@ back to an in-memory store, so naive caching works out of the box.
662
665
  ### AI / ML
663
666
 
664
667
  ```plainscript
665
- remember reply as chat("gpt-4o-mini", [
666
- { role: "user", content: "Say hello in two words" }
667
- ])
668
+ let reply be chat("gpt-4o-mini", list with
669
+ record with role "user" and content "Say hello in two words"
670
+ done)
668
671
 
669
- remember vec as embedText("text-embedding-3-small", "PlainScript rocks")
670
- remember score as similarity(vec, embedText("text-embedding-3-small", "I love PlainScript"))
672
+ let vec be embedText("text-embedding-3-small", "PlainScript rocks")
673
+ let score be similarity(vec, embedText("text-embedding-3-small", "I love PlainScript"))
671
674
 
672
- remember tags as ai_tags("PlainScript is an intent-oriented language")
673
- remember article as ai_post("Welcome to PlainScript", ["why IOPL", "quick start"])
675
+ let tags be ai_tags("PlainScript is an intent-oriented language")
676
+ let article be ai_post("Welcome to PlainScript", list with "why IOPL", "quick start")
674
677
  ```
675
678
 
676
679
  `chat` and `embedText` are async OpenAI-compatible calls (from `OPENAI_API_KEY`,
@@ -679,21 +682,21 @@ override with `options.apiKey`/`options.baseURL`); `similarity` returns -1..1.
679
682
  ### Pagination
680
683
 
681
684
  ```plainscript
682
- remember page as paginate(allUsers, 2, 10)
685
+ let page be paginate(allUsers, 2, 10)
683
686
  show page.items # second page of 10
684
687
  show page.hasNext # true if another page exists
685
688
  ```
686
689
 
687
690
  `paginate(list, page, perPage)` returns
688
- `{ items, count, page, pages, perPage, hasNext, hasPrev }`.
691
+ `record with items, count, page, pages, perPage, hasNext, hasPrev done`.
689
692
 
690
693
  ---
691
694
 
692
695
  ## Multi-file projects
693
696
 
694
697
  ```plainscript
695
- import "./math.ps"
696
- import "./utils.ps"
698
+ import "./math.pln"
699
+ import "./utils.pln"
697
700
 
698
701
  show PI
699
702
 
@@ -710,16 +713,16 @@ standalone output under `dist/`, with imported code inlined.
710
713
  ```plainscript
711
714
  use express
712
715
 
713
- remember app as express()
716
+ let app be express()
714
717
 
715
718
  serve folder "public"
716
719
 
717
720
  when someone visits "/"
718
- reply "Hello from PlainScript!"
721
+ show "Hello from PlainScript!"
719
722
  done
720
723
 
721
724
  when someone visits "/api/status"
722
- reply json
725
+ show json
723
726
  status is "ok"
724
727
  version is "0.3"
725
728
  done
@@ -746,12 +749,12 @@ whatsapp bot
746
749
  on message
747
750
  log message // print the normalized record
748
751
 
749
- if message.text is "/start"
750
- reply "Welcome!"
752
+ when message.text is "/start"
753
+ show "Welcome!"
751
754
  done
752
755
 
753
- if message.text is "/help"
754
- reply `Available commands:
756
+ when message.text is "/help"
757
+ show `Available commands:
755
758
  /start /help`
756
759
  done
757
760
  done
@@ -764,17 +767,17 @@ done
764
767
  - `login pairing` also accepts any value — prompt for the number
765
768
  at runtime instead of hard-coding it:
766
769
 
767
- ```plainscript
768
- ask "WhatsApp number: " as phone
770
+ ```plainscript
771
+ ask "WhatsApp number: " as phone
769
772
 
770
- whatsapp bot
771
- auth "session"
772
- login pairing phone
773
- done
774
- ```
773
+ whatsapp bot
774
+ auth "session"
775
+ login pairing phone
776
+ done
777
+ ```
775
778
 
776
- - Inside `on message`, `message` holds `{ text, chat, sender, name, id,
777
- time, isGroup }`; `reply` answers the current chat.
779
+ - Inside `on message`, `message` holds `record with text, chat, sender, name, id,
780
+ time, isGroup done`; `print` answers the current chat.
778
781
  - The bot ignores its own messages and status broadcasts and keeps working in
779
782
  groups; transient disconnects reconnect after 3 seconds.
780
783
 
@@ -789,7 +792,7 @@ plainscript install # Install all detected dependencies
789
792
  plainscript add express # Add a package
790
793
  plainscript remove express # Remove a package
791
794
  plainscript update # Update all packages
792
- plainscript start # Build src/app.ps and run its dist/ output
795
+ plainscript start # Build src/app.pln and run its dist/ output
793
796
  plainscript doctor # Check project environment
794
797
  ```
795
798
 
@@ -832,27 +835,27 @@ plainscript/
832
835
  │ └── cli.js — command-line entry point
833
836
  │
834
837
  ├── examples/
835
- │ ├── hello.ps
836
- │ ├── day2.ps
837
- │ ├── day3.ps
838
- │ ├── arrays.ps
839
- │ ├── objects.ps
840
- │ ├── loops.ps
841
- │ ├── expressions.ps
842
- │ ├── stdlib.ps
843
- │ ├── server.ps
844
- │ ├── web-app.ps
845
- │ ├── start.ps
846
- │ ├── database.ps
847
- │ ├── deployment.ps
838
+ │ ├── hello.pln
839
+ │ ├── day2.pln
840
+ │ ├── day3.pln
841
+ │ ├── arrays.pln
842
+ │ ├── objects.pln
843
+ │ ├── loops.pln
844
+ │ ├── expressions.pln
845
+ │ ├── stdlib.pln
846
+ │ ├── server.pln
847
+ │ ├── web-app.pln
848
+ │ ├── start.pln
849
+ │ ├── database.pln
850
+ │ ├── deployment.pln
848
851
  │ ├── football-backend/ — acceptance example (SQLite + auth + sessions)
849
- │ │ └── app.ps
852
+ │ │ └── app.pln
850
853
  │ ├── id-verification/ — acceptance example (uploads + OCR matching)
851
- │ │ ├── app.ps
854
+ │ │ ├── app.pln
852
855
  │ │ └── make-sample-id.js
853
856
  │ └── whatsapp-bot/ — WhatsApp bots (QR and pairing linking)
854
- │ ├── qr.ps
855
- │ └── pairing.ps
857
+ │ ├── qr.pln
858
+ │ └── pairing.pln
856
859
  │
857
860
  ├── tests/
858
861
  │ ├── compiler.test.js — language, CLI and formatter coverage
@@ -865,9 +868,13 @@ plainscript/
865
868
  │ └── acceptance.test.js — boots the example projects over live HTTP
866
869
  │
867
870
  ├── docs/
868
- │ ├── PlainScript_SPEC.md
871
+ │ ├── PLAINSCRIPT-SPEC.md
869
872
  │ └── index.html
870
873
  │
874
+ ├── editors/
875
+ │ └── mt-manager/
876
+ │ └── plainscript.mtsx — MT Manager syntax highlighting
877
+ │
871
878
  ├── package.json
872
879
  └── README.md
873
- ```
880
+ ```