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/README.md CHANGED
@@ -1,344 +1,1195 @@
1
+ <div align="center">
2
+
3
+ <img src="https://raw.githubusercontent.com/ayoistooslick/plainscript/main/docs/logo-pln.jpg" alt="PlainScript logo" width="220" />
4
+
1
5
  # PlainScript
2
6
 
7
+ **An Intent-Oriented Programming Language (IOPL).**
8
+ Describe *what* you want. The compiler decides *how* to implement it in JavaScript.
9
+
3
10
  [![CI](https://github.com/ayoistooslick/plainscript/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/ayoistooslick/plainscript/actions/workflows/npm-publish.yml)
11
+ [![npm version](https://img.shields.io/npm/v/plainscript-lang.svg)](https://www.npmjs.com/package/plainscript-lang)
12
+ [![Downloads](https://img.shields.io/npm/dm/plainscript-lang.svg)](https://www.npmjs.com/package/plainscript-lang)
13
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
14
+
15
+ [Quick Start](#quick-start) ·
16
+ [Language Tour](#language-tour) ·
17
+ [Backend Services](#backend-services) ·
18
+ [CLI Reference](#cli-reference) ·
19
+ [Contributing](#contributing)
20
+
21
+ </div>
22
+
23
+ ---
24
+
25
+ ## Table of Contents
26
+
27
+ - [Why PlainScript](#why-plainscript)
28
+ - [Quick Start](#quick-start)
29
+ - [CLI Reference](#cli-reference)
30
+ - [Building &amp; Configuration](#building--configuration)
31
+ - [Language Tour](#language-tour)
32
+ - [Variables](#variables)
33
+ - [String Templates](#string-templates)
34
+ - [Conditions](#conditions)
35
+ - [Conditional expressions](#conditional-expressions)
36
+ - [Functions](#functions)
37
+ - [Lambdas](#lambdas)
38
+ - [Arrays &amp; Objects](#arrays--objects)
39
+ - [Dictionaries, Sets &amp; Tuples](#dictionaries-sets--tuples)
40
+ - [Loops](#loops)
41
+ - [Natural-Language Expressions](#natural-language-expressions)
42
+ - [Logical Assignment](#logical-assignment)
43
+ - [Error handling, async, and events](#error-handling-async-and-events)
44
+ - [Record Kinds, Concurrency &amp; More](#record-kinds-concurrency--more)
45
+ - [Backend Services](#backend-services)
46
+ - [Databases](#databases)
47
+ - [HTTP Client](#http-client)
48
+ - [Authentication](#authentication)
49
+ - [Sessions &amp; Cookies](#sessions--cookies)
50
+ - [File Uploads](#file-uploads)
51
+ - [Rate Limiting](#rate-limiting)
52
+ - [Google OAuth](#google-oauth)
53
+ - [Error Handling &amp; Retries](#error-handling--retries)
54
+ - [Runtime Standard Library](#runtime-standard-library)
55
+ - [Web Applications](#web-applications)
56
+ - [Browser games and interactive apps](#browser-games-and-interactive-apps)
57
+ - [Additional Backend Capabilities](#additional-backend-capabilities)
58
+ - [HTTP Routing](#http-routing)
59
+ - [Transactions](#transactions)
60
+ - [Email](#email)
61
+ - [Cron &amp; Background Jobs](#cron--background-jobs)
62
+ - [WebSockets](#websockets)
63
+ - [Cache](#cache)
64
+ - [AI / ML](#ai--ml)
65
+ - [Pagination](#pagination)
66
+ - [Multi-File Projects](#multi-file-projects)
67
+ - [Express Integration](#express-integration)
68
+ - [WhatsApp Bots](#whatsapp-bots)
69
+ - [Supported Packages](#supported-packages)
70
+ - [Project Structure](#project-structure)
71
+ - [Running the Tests](#running-the-tests)
72
+ - [Contributing](#contributing)
73
+ - [License](#license)
74
+
75
+ ---
76
+
77
+ ## Why PlainScript
78
+
79
+ Most languages ask you to describe *how* a computation happens: loop constructs, control flow, boilerplate. PlainScript inverts that. You write source that reads like an instruction to a competent engineer, and a deterministic compiler - no rules engine, no AI, no hidden codegen - turns it into JavaScript.
80
+
81
+ | | |
82
+ |---|---|
83
+ | **Deterministic** | Rebuilds are byte-identical. Safe to commit, diff, and cache. |
84
+ | **Zero configuration** | `plainscript build` discovers sources and compiles them with no setup. |
85
+ | **Standard packaging** | Ships as normal `npm` packages; consumers `require()` the output like any Node module. |
86
+ | **Batteries included** | HTTP, SQLite/Postgres, sessions, auth, cron, WebSockets, and WhatsApp bots are language features, not add-on libraries. |
87
+
88
+ A short comparison of the same logic in JavaScript and PlainScript:
89
+
90
+ <table>
91
+ <tr>
92
+ <th>JavaScript</th>
93
+ <th>PlainScript</th>
94
+ </tr>
95
+ <tr>
96
+ <td>
97
+
98
+ ```js
99
+ function classify(age) {
100
+ if (age >= 18) {
101
+ return "Adult";
102
+ } else {
103
+ return "Teenager";
104
+ }
105
+ }
106
+ ```
107
+
108
+ </td>
109
+ <td>
110
+
111
+ ```
112
+ to classify age
113
+ when age is at least 18
114
+ give back "Adult"
115
+ otherwise
116
+ give back "Teenager"
117
+ done
118
+ done
119
+ ```
4
120
 
5
- PlainScript is a programming language that reads like English and runs on Node.js. You write `.pln` files, and PlainScript turns them into JavaScript you can run anywhere.
121
+ </td>
122
+ </tr>
123
+ </table>
6
124
 
7
- ## Get started in 60 seconds
125
+ **Current version:** `v1.0.361` - the `plainscript-lang` npm package, with a TypeScript-style production build (`plainscript build` → `dist/`, source names and structure preserved).
126
+
127
+ ---
128
+
129
+ ## Quick Start
8
130
 
9
131
  ```bash
10
- npx plainscript new hello
11
- cd hello
12
- npm install
13
- npx plainscript check
14
- npm run build
15
- npm start
132
+ npx plainscript new myapp # scaffolds src/app.pln and package.json
133
+ cd myapp
134
+ npm install # installs the compiler and runtime packages
135
+ npm run build # compiles src/ -> dist/ (plainscript build)
136
+ node dist/app.js # or: npm start
16
137
  ```
17
138
 
18
- Run a single file without saving any build output:
139
+ Adding PlainScript to an existing project:
19
140
 
20
141
  ```bash
21
- npx plainscript run examples/basics.pln
142
+ npm install --save-dev plainscript-lang
143
+ # start writing src/*.pln files - plainscript build auto-discovers them
22
144
  ```
23
145
 
24
- ## Commands
146
+ No global install is required. Everything runs through `npm` scripts and `npx`.
147
+
148
+ ### Supported Node.js and dependency policy
25
149
 
26
- | Command | What it does |
27
- | --- | --- |
28
- | `plainscript new [name]` | Create a new project |
29
- | `plainscript check` | Validate your code |
30
- | `plainscript build` | Compile to JavaScript in `dist/` |
31
- | `plainscript run <file>` | Check, install, and run a file |
32
- | `plainscript start` | Build and start `src/app.pln` |
33
- | `plainscript fmt <file>` | Format your code |
34
- | `plainscript add <package>` | Add an npm package |
35
- | `plainscript remove <package>` | Remove an npm package |
36
- | `plainscript update` | Update installed packages |
37
- | `plainscript doctor` | Check your project setup |
38
- | `plainscript version` | Print version |
150
+ The compiler and its checked-in dependency tree support **Node.js 18 or newer**.
151
+ Use the lockfile for reproducible installs:
39
152
 
40
- Run `plainscript check` after every change — it validates your code and catches errors early.
153
+ ```bash
154
+ npm ci
155
+ ```
41
156
 
42
- ## Syntax
157
+ The compiler package intentionally does not install the optional WhatsApp
158
+ adapter. This keeps a normal `npm ci` independent of Baileys' native/GitHub
159
+ transitives and lets projects that do not use WhatsApp install cleanly on the
160
+ Node 18 floor. The SQLite, MongoDB, and Redis versions in `package.json` are
161
+ the last compatible major lines for that floor.
43
162
 
44
- ### Variables and output
163
+ WhatsApp projects have a separate adapter requirement. `plainscript install`
164
+ uses the pinned default `@whiskeysockets/baileys@6.7.24` (Node.js 20 or newer)
165
+ and `qrcode-terminal`. If a package firewall or registry cannot provide that
166
+ adapter, install a Baileys-compatible package or local fork yourself and select
167
+ it in the bot block:
45
168
 
46
169
  ```plainscript
47
- remember name as "Ada"
48
- let count is 3
49
- let greeting is `Hello, ${name}!`
170
+ whatsapp bot
171
+ use baileys "./vendor/baileys"
172
+ auth "session"
173
+ login qr
174
+ done
175
+ ```
176
+
177
+ For a local adapter, install it from the project directory (for example,
178
+ `npm install ./vendor/baileys`) and ensure it exposes the Baileys default
179
+ socket export plus `useMultiFileAuthState`, `makeCacheableSignalKeyStore`, and
180
+ `DisconnectReason`. Local adapter paths are not passed to `npm install` by
181
+ `plainscript install`.
182
+
183
+ ---
184
+
185
+ ## CLI Reference
186
+
187
+ | Command | Description |
188
+ |---|---|
189
+ | `plainscript run <file.pln>` | Installs missing dependencies, compiles, and executes. Runs from a scratch directory - nothing is written into your project. |
190
+ | `plainscript build [file.pln]` | Compiles to `dist/`. With no argument, builds every `.pln` file under the source root, preserving names and folder structure. |
191
+ | `plainscript check <file.pln>` | Checks syntax only. No output, no execution. |
192
+ | `plainscript fmt <file.pln>` | Formats a PlainScript file in place. |
193
+ | `plainscript new [name]` | Creates a new PlainScript project, npm-ready. |
194
+ | `plainscript install` | Installs dependencies detected across the project's sources. |
195
+ | `plainscript start` | Builds `src/app.pln` and runs its `dist/` output. |
196
+ | `plainscript doctor` | Checks the PlainScript project environment. |
197
+ | `plainscript add <package>` | Installs a package into the project. |
198
+ | `plainscript remove <package>` | Uninstalls a package from the project. |
199
+ | `plainscript update` | Updates all installed npm packages. |
200
+ | `plainscript version` | Prints the compiler version. |
201
+ | `plainscript help` | Prints help text. |
202
+
203
+ ---
204
+
205
+ ## Building &amp; Configuration
206
+
207
+ `plainscript build` is a deterministic production build - TypeScript-style, but for `.pln` sources - with zero configuration required.
208
+
209
+ - Run with no argument and it discovers every `.pln` file under `src/`, compiling each to `dist/` while **preserving source file names and folder structure**: `src/messi.pln` → `dist/messi.js`, `src/helpers/math.pln` → `dist/helpers/math.js`.
210
+ - `plainscript build <file.pln>` compiles a single file into `dist/`.
211
+ - Imports are bundled into each output, so every file in `dist/` runs standalone under Node.
212
+ - Rebuilds are byte-identical, making them safe to commit, diff, and cache.
213
+
214
+ Source discovery skips `node_modules`, hidden directories, and the output directory itself. When no `src/` directory exists, the project root is scanned instead.
215
+
216
+ ### Optional `plainscript.config.json`
217
+
218
+ For projects that need custom output or source directories, add a `plainscript.config.json` with a `compilerOptions` block, similar to `tsconfig.json`:
219
+
220
+ ```json
221
+ {
222
+ "compilerOptions": {
223
+ "outDir": "./build",
224
+ "rootDir": "./lib",
225
+ "exclude": ["vendor"]
226
+ }
227
+ }
228
+ ```
229
+
230
+ ### Publishing a Library Written in PlainScript
231
+
232
+ ```json
233
+ {
234
+ "name": "my-plainscript-library",
235
+ "main": "dist/index.js",
236
+ "scripts": {
237
+ "build": "plainscript build",
238
+ "prepare": "plainscript build"
239
+ },
240
+ "devDependencies": { "plainscript-lang": "^1.0.361" }
241
+ }
242
+ ```
243
+
244
+ `src/index.pln` builds to `dist/index.js`; consumers install and `require()` it like any Node package. There is no PlainScript-specific registry or format - standard `package.json` semantics apply.
245
+
246
+ ---
247
+
248
+ ## Language Tour
249
+
250
+ PlainScript is a fixed vocabulary of English verbs compiled to JavaScript. Every
251
+ construct follows the same rhythm: a word opens a block, `done` closes it, and
252
+ `give` returns a value - a sentence you could say to a colleague ("if the score
253
+ is at least 80, show accepted, otherwise review") is valid source. The sections
254
+ below keep the code first, with a short note on what each construct is *for* and
255
+ the constraint that matters when you use it.
256
+
257
+ ### Variables
258
+
259
+ ```
260
+ let name be "Ayokunle"
261
+ let age be 16
262
+ set age to 17
263
+ ```
264
+
265
+ `remember name as "Ada"` and `let name be "Ada"` are two spellings of the same
266
+ declaration; `set name to ...`, `name becomes ...`, and `name is now ...` all
267
+ reassign it. Numbers, strings, and booleans behave like JavaScript primitives;
268
+ lists, records, dictionaries, and sets are *references*, so pointing two names
269
+ at the same list means they see the same data.
270
+
271
+ ### String Templates
272
+
273
+ Backtick-delimited strings preserve whitespace and support `${expression}` interpolation:
274
+
275
+ ```
276
+ let name be "World"
277
+ let greeting be `Hello ${name}!`
50
278
  show greeting
51
- count becomes count + 1
279
+
280
+ let email be `Dear ${customer},
281
+
282
+ Thank you for your order #${orderId}.
283
+
284
+ Best regards,
285
+ The Team`
52
286
  ```
53
287
 
54
- `remember name as value` declares a variable. `show`, `print`, and `display` all print output.
288
+ Interpolation compiles directly to JavaScript template literals - it is not evaluated at compile time. Literal dollar signs without `{` are preserved as-is.
55
289
 
56
290
  ### Conditions
57
291
 
58
- ```plainscript
59
- if score is at least 80 and status is not "blocked"
60
- show "accepted"
292
+ `if <condition> ... done` runs its block when the condition is true, and the
293
+ optional `otherwise` block runs when it is false (`when ... done` is the same
294
+ statement used in web and event contexts). Conditions read like English, and a
295
+ comparison is itself a value: `score is at least 80` is `true` or `false`, so it
296
+ can be stored, printed, passed to a function, or joined with `and` / `or` /
297
+ `not`. When you need a *value* rather than a block, use `choosing` (below).
298
+
299
+ ```
300
+ when age is at least 18
301
+ show "Adult"
61
302
  otherwise
62
- show "review"
303
+ show "Teenager"
63
304
  done
64
- ```
65
305
 
66
- You can use `is`, `more than`, `fewer than`, `contains`, `starts with`, `ends with`, `and`, `or`, and `not`.
306
+ when name contains "PlainScript"
307
+ show "Found it"
308
+ done
67
309
 
68
- ### Lists and records
310
+ when score between 90 and 100
311
+ show "A grade"
312
+ done
313
+ ```
69
314
 
70
- ```plainscript
71
- remember players as list with "Ada", "Grace", "Lin"
72
- show players at position 1
315
+ All comparison operators:
316
+
317
+ | PlainScript | JavaScript |
318
+ |---|---|
319
+ | `is` / `is equal to` | `===` |
320
+ | `same as` | `===` |
321
+ | `is not` | `!==` |
322
+ | `different from` | `!==` |
323
+ | `is greater than` / `is above` | `>` |
324
+ | `more than` | `>` |
325
+ | `is less than` / `is below` | `<` |
326
+ | `fewer than` | `<` |
327
+ | `is at least` | `>=` |
328
+ | `is at most` | `<=` |
329
+ | `is empty` | `.length === 0` |
330
+ | `is not empty` | `.length > 0` |
331
+ | `contains "x"` | `.includes("x")` |
332
+ | `made of "x"` | `.includes("x")` |
333
+ | `starts with "x"` / `starts as "x"` | `.startsWith("x")` |
334
+ | `ends with "x"` / `ends as "x"` | `.endsWith("x")` |
335
+ | `between A and B` | `>= A &amp;&amp; <= B` |
336
+ | `has field "x"` | `"x" in obj` |
337
+ | `at position key` | `obj[key]` |
338
+
339
+ ### Conditional expressions
340
+
341
+ `choosing` is the value form of `if`: pick between two expressions and keep the
342
+ whole thing inline - in an argument, a `give`, or a list element.
73
343
 
74
- remember user as record with name "Ada" and active true done
75
- show user.name
344
+ ```
345
+ remember verdict as choosing score is at least 90 then "A" otherwise "B"
346
+ show choosing score is below 60 then "low" otherwise "ok"
76
347
  ```
77
348
 
78
- You can also use plain JavaScript arrays and objects: `[1, 2, 3]` and `{name: "Ada"}`.
349
+ `choosing <condition> then <a> otherwise <b>` evaluates to `<a>` when the
350
+ condition is true and `<b>` otherwise.
79
351
 
80
352
  ### Functions
81
353
 
82
- ```plainscript
83
- make add(a, b)
84
- give a + b
354
+ ```
355
+ to add a and b together
356
+ give back a + b
357
+ done
358
+ show add(5, 7)
359
+
360
+ to multiply x and y together
361
+ give back x * y
85
362
  done
363
+ ```
364
+
365
+ `make name(args)` and its `to ... together` spelling define a function; `done`
366
+ closes it - the PlainScript form of JavaScript's `function`. `give <value>` (or
367
+ `give back <value>`) returns; `give` alone simply ends the function. A `make`
368
+ function is a value like any other, so it can be stored with `remember`, passed
369
+ as an argument, or returned from another function. Arguments are optional with
370
+ defaults: `make label(name as "guest")`.
86
371
 
372
+ ### Lambdas
373
+
374
+ A lambda is a function without a name, written where a value is expected -
375
+ `(a, b) -> a + b` is JavaScript's `(a, b) => a + b`. Use the arrow form for a
376
+ one-expression body and the `do ... done` form when the body has several
377
+ statements:
378
+
379
+ ```
380
+ remember add as (a, b) -> a + b
87
381
  show add(2, 3)
382
+
383
+ remember grade as (score) do
384
+ if score is at least 90
385
+ give "excellent"
386
+ otherwise
387
+ give "keep practicing"
388
+ done
389
+ done
390
+
391
+ remember doubled as numbers.map((n) -> n * 2)
88
392
  ```
89
393
 
90
- ```plainscript
91
- make greet(name as "friend")
92
- give `Hello, ${name}`
394
+ Lambdas are ordinary values: store them, put them in lists and records, pass
395
+ them to `.map` / `.filter` / `.find` / `.forEach`, and return or chain them
396
+ (`mul(2)(3)(5)`) to build factories and curried helpers.
397
+
398
+ ### Arrays &amp; Objects
399
+
400
+ `list with ...` is PlainScript's spelling of an array; `record with ... done`
401
+ is a plain object. Both are ordinary values, so lists hold records, records
402
+ hold lists, and lambdas can live anywhere a value can. Read and write them with
403
+ `.name`, `[index]`, or the natural-language forms later in this tour.
404
+
405
+ ```
406
+ let players be list with "Haaland", "Foden", "Rodri"
407
+ show players[0]
408
+ set players[1] to "Palmer"
409
+
410
+ let user be record with
411
+ name "Ayokunle"
412
+ age 17
93
413
  done
414
+ show user.name
94
415
  ```
95
416
 
417
+ ### Dictionaries, Sets & Tuples
418
+
419
+ JavaScript's `Map` and `Set` have direct spellings, and tuples are fixed-size
420
+ arrays you usually unpack all at once:
421
+
422
+ ```
423
+ remember lookup as dictionary with "alpha" is 1 and "beta" is 2 done
424
+ show lookup.get("beta") // 2
425
+
426
+ remember tags as set with "admin", "editor", "admin" done // duplicates collapse
427
+
428
+ remember point as tuple with 10, 20 and 30 done
429
+ unpack point into x, y and z // x=10, y=20, z=30
430
+ show x + y + z
431
+ ```
432
+
433
+ Dictionary and set entries are joined with `and`; a tuple separates its members
434
+ with commas and `and` before the final member. `show <value>` accepts any value,
435
+ and JSON data arrives as nested lists and records.
436
+
96
437
  ### Loops
97
438
 
98
- ```plainscript
439
+ `for each item in <collection> ... done` visits every element, and `while
440
+ <condition> ... done` repeats until the condition is false. Counted loops come
441
+ in sentence form too:
442
+
443
+ ```
444
+ repeat 5 times
445
+ show "tick"
446
+ done
447
+
448
+ remember energy as 9
449
+ repeat while energy is above 0
450
+ energy becomes energy - 1
451
+ done
452
+ ```
453
+
454
+ `for every item in basket` is an alias for `for each`, `repeat until <condition>`
455
+ flips the `while` sense, and `for index i from 0 to 9` gives a zero-based
456
+ counter when you need positions.
457
+
458
+ ```
99
459
  for each player in players
100
460
  show player
101
461
  done
102
462
 
103
- for index position from 0 to 2
104
- show position
463
+ for every item in basket // alias for "for each"
464
+ show item
105
465
  done
106
466
 
107
- while attempts is less than 3
108
- attempts becomes attempts + 1
467
+ while age is less than 18
468
+ set age to age + 1
109
469
  done
110
470
  ```
111
471
 
112
- ### Record kinds
472
+ ### Natural-Language Expressions
113
473
 
114
- ```plainscript
474
+ Collections, properties, and files read like sentences.
475
+
476
+ **Items**
477
+
478
+ ```
479
+ let players be list with "Haaland", "Foden", "Rodri"
480
+
481
+ show first player from players // players[0]
482
+ show last player from players // players[players.length - 1]
483
+ show player two from players // players[1]
484
+ first player from players is now "Haaland" // players[0] = "Haaland"
485
+ ```
486
+
487
+ Number words from `one` to `twenty` map to one-based positions - `player one` is the first item.
488
+
489
+ **Collections**
490
+
491
+ ```
492
+ show players length // players.length
493
+ add("Palmer" to players) // players.push("Palmer")
494
+ remove("Rodri" from players) // players.splice(players.indexOf("Rodri"), 1)
495
+
496
+ when players contains "Foden" // players.includes("Foden")
497
+ show "Found"
498
+ done
499
+ ```
500
+
501
+ **Properties**
502
+
503
+ ```
504
+ show name of user // user.name
505
+ show city of address of customer // customer.address.city
506
+ name of user is now "Ayo" // user.name = "Ayo"
507
+ ```
508
+
509
+ `of` chains right-to-left: `city of address of customer` reads as the city of the address of the customer.
510
+
511
+ **Files**
512
+
513
+ ```
514
+ let data be read("users.txt") // fs.readFileSync("users.txt", 'utf8')
515
+ write(data to "users.txt") // fs.writeFileSync(data, "users.txt", 'utf8')
516
+ ```
517
+
518
+ The older `readFile()` / `writeFile()` forms still work and are unchanged.
519
+
520
+ ### Logical Assignment
521
+
522
+ The word-style assignment operators keep the common "fill the empty value"
523
+ pattern on one line - PlainScript for `flag = flag || true` and
524
+ `val = val ?? "default"`:
525
+
526
+ ```
527
+ let flag be false
528
+ flag or is now true
529
+ show flag
530
+
531
+ let val be null
532
+ val nullish is now "default"
533
+ show val
534
+ ```
535
+
536
+ ### Error handling, async, and events
537
+
538
+ Programs that fail should say so. `raise <value>` throws an error, `try` /
539
+ `recover as err` / `finally` catch it, and `retry N times every Mms` re-runs a
540
+ block that may fail transiently:
541
+
542
+ ```
543
+ raise "not implemented"
544
+
545
+ try
546
+ remember data as jsonDecode(raw)
547
+ recover as err
548
+ show "bad json: " + message of err
549
+ finally
550
+ show "request complete"
551
+ done
552
+
553
+ retry 3 times every 2 seconds
554
+ show "fetching..."
555
+ done
556
+ ```
557
+
558
+ Asynchronous work uses `wait for <promise>` (or `await <promise>`). A `make`
559
+ function or lambda that `wait for`s a promise becomes async automatically, and
560
+ `all of [...]`, `any of [...]`, and `settled of [...]` run several promises at
561
+ once. Events bind with `when <target> "<event>" happens [as <name>] ... done` -
562
+ the DOM equivalent of `addEventListener` - and server/websocket forms follow
563
+ the same `when ... done` pattern.
564
+
565
+ ### Record Kinds, Concurrency &amp; More
566
+
567
+ For the shapes that repeat in a program - a user, a message, an order - declare
568
+ a **record kind** and construct instances with `create`. Kinds behave like
569
+ plain objects with a known field list: setting an unknown field throws, which
570
+ catches typos early.
571
+
572
+ ```
115
573
  define a kind called "Player" with
116
574
  name is ""
117
575
  goals is 0
118
576
  done
119
577
 
120
578
  remember player as create a Player with name "Ada" and goals 4
579
+ player.goals becomes player.goals + 1
580
+ show player.goals
121
581
  ```
122
582
 
123
- ### Compound data structures
583
+ PlainScript 1.0.2 closes most of the gap with TypeScript-class languages using its own grammar. The full audit lives in [`docs/CAPABILITY_GAP_AUDIT.md`](./docs/CAPABILITY_GAP_AUDIT.md).
124
584
 
125
- ```plainscript
126
- // Dictionaries
127
- remember userMap as dictionary with "name" is "Ada" and "role" is "admin" done
128
- put "role" as "editor" in userMap
129
- remember mapKeys as keys of userMap
585
+ <details>
586
+ <summary>Expand full feature list</summary>
587
+
588
+ | Category | Features |
589
+ |---|---|
590
+ | Record kinds (classes) | `to define a kind called "Person" with name "" end`, then `create a Person with name "Ada" and age 17`. Plain-object instances; unknown fields throw. |
591
+ | Concurrency | `all of [...]`, `any of [...]`, `settled of [...]`, `withTimeout(promise, ms)` |
592
+ | Generators | `yield` inside `define ... end`; consumed with `for each` or `spread of` |
593
+ | Reflection | `typeOf`, `fieldsOf`, `valueOf`, `hasField`, `sizeOf` |
594
+ | Binary | `base64Encode/Decode`, `textToBytes/bytesToText`, `sha256/sha1/md5` |
595
+ | Config | `yamlDecode/yamlEncode`, `load env file ".env"` |
596
+ | CLI &amp; processes | `args()`, `runCommand(cmd, [args])` |
597
+ | Filesystem &amp; paths | `fileSize`, `fileType`, `lastModified`, `walkFolder`, `joinPath`, `baseName`, `folderOf`, `extensionOf` |
598
+ | Streams | `writeLine`, `appendLine` |
599
+ | Collections | `keyMap/mapSet/mapGet/mapHas/mapDelete`, `newSet/addToSet` |
600
+ | Dynamic modules | `loadModule("./m")` |
601
+ | Native tests | `test "name" ... end` with `check a equals b`, `check a contains b`, `check a is b`, `check <expr> raises "msg"` |
602
+ | Exports | `export <name>` |
603
+
604
+ </details>
130
605
 
131
- // Sets
132
- remember tags as set with "admin", "editor", "user" done
133
- remember newTags as union of tags and (set with "moderator" done)
606
+ **How the pieces fit together.** PlainScript is deliberately small: a handful
607
+ of verbs (`remember`, `give`, `if` / `otherwise`, `done`) plus the collections
608
+ and functions you just met. Everything is a value - numbers and strings,
609
+ comparisons, collections, lambdas, whole functions - so pieces nest instead of
610
+ needing new syntax: a lambda inside a list, a comparison handed to a filter, a
611
+ `make` function stored in a record. When a pattern repeats, extract it into a
612
+ `make` function (or a lambda), group related names into a module, and call the
613
+ abstraction the same way you call `show` or `jsonDecode`. The standard library
614
+ and the backend capabilities that follow are exactly this: vocabulary built on
615
+ the primitives above, available to every program.
616
+
617
+ ---
618
+
619
+ ## Backend Services
620
+
621
+ Everything in this section is compiled by the deterministic compiler - no rules, no AI, no hidden codegen.
622
+
623
+ ### Databases
624
+
625
+ Portable databases (SQLite native or WebAssembly):
134
626
 
135
- // Tuples
136
- remember point as tuple with 10, 20, 30 done
137
- unpack point into x, y, z
627
+ ```
628
+ database "app.db" // probes better-sqlite3, falls back to sql.js
138
629
  ```
139
630
 
140
- ### Imports and exports
631
+ `plainscript install` verifies that `better-sqlite3` actually loads. If the native module cannot be used, PlainScript warns and continues on the pure-JavaScript WebAssembly engine (`sql.js`) - the same program runs unchanged. An engine can be forced explicitly:
141
632
 
142
- ```plainscript
143
- // Import specific functions
144
- bring circleArea and squareArea from "./math.pln"
633
+ ```
634
+ database "app.db" using "native" // hard requirement: better-sqlite3
635
+ database "app.db" using "wasm" // hard requirement: sql.js
636
+ ```
145
637
 
146
- // Import with a namespace
147
- bring all from "./math.pln" as math
148
- show math.circleArea(5)
638
+ The WebAssembly engine persists the whole database to disk after every write, so data survives restarts either way.
149
639
 
150
- // Import an npm package
151
- bring axios from "axios"
640
+ ### HTTP Client
152
641
 
153
- // Use @/ to import from src/
154
- bring button from "@/components/button.pln"
642
+ ```
643
+ let r be get "https://api.example.com/users"
644
+ when ok of r
645
+ show status of r
646
+ show data of r
647
+ done
155
648
 
156
- // Re-export everything from another file
157
- export all from "./submodule.pln"
649
+ let created be post url with body
650
+ headers record with accept "application/json" done
651
+ timeout 5000
158
652
  ```
159
653
 
160
- ## AI providers
654
+ Methods: `get`, `post … with <body>`, `put`, `patch`, `delete "<url>"`. Responses are records: `ok`, `status`, `headers`, `data` (JSON is parsed automatically). The default timeout is 30 seconds; `wait for fetch(...)` awaits raw promises when needed.
161
655
 
162
- PlainScript can call AI models from any provider that supports the OpenAI API format. Your API keys stay in environment variables.
656
+ ### Authentication
163
657
 
164
- ```plainscript
165
- remember answer as chat("llama-3.3-70b-versatile", "Summarize PlainScript", {
166
- provider: "groq",
167
- key: env("GROQ_API_KEY"),
168
- temperature: 0.2
169
- })
170
- show answer
171
658
  ```
659
+ let hash be hashPassword("correct horse")
660
+ when checkPassword(password of body of request, hash)
661
+ let token be createToken(user, env("TOKEN_SECRET"), 3600)
662
+ done
172
663
 
173
- Supported providers: `groq`, `openai`, `openrouter`, `together`, `fireworks`, `deepseek`. You can also point to any custom OpenAI-compatible endpoint with `base`, `key`, and `headers`.
664
+ let payload be readToken(token, env("TOKEN_SECRET"))
665
+ ```
174
666
 
175
- ## Telegram bots
667
+ `hashPassword` / `checkPassword` use scrypt; tokens are HMAC-signed with an expiry and fail closed on tampering or timeout.
176
668
 
177
- ```plainscript
178
- bot env("TELEGRAM_BOT_TOKEN")
179
- when someone sends "/start"
180
- reply "Welcome"
669
+ ### Sessions &amp; Cookies
670
+
671
+ ```
672
+ web app
673
+ enable sessions "a-long-random-secret"
674
+
675
+ route post "/login"
676
+ user of session of request is username of body of request
677
+ show "welcome"
181
678
  done
182
- when someone sends matching "/ask (.+)"
183
- remember answer as chatWith("groq", "llama-3.3-70b-versatile", message)
184
- reply answer
679
+
680
+ route get "/me"
681
+ show user of session of request
682
+ done
683
+
684
+ route post "/logout"
685
+ destroy session
686
+ show "bye"
185
687
  done
186
- start telegram bot
187
688
  ```
188
689
 
189
- Inside a handler, `message`, `args`, `matches`, `chat`, and `chatId` give you access to the current update.
690
+ Sessions ride an HMAC-signed `HttpOnly` cookie (`plainscript.sid`). The store is in-memory: restarting the server signs everyone out.
190
691
 
191
- ## Standard library
692
+ ```
693
+ set cookie "theme" to "dark" expires in 7 days
694
+ show cookie("theme")
695
+ clear cookie "theme"
696
+ ```
192
697
 
193
- No imports needed — these work out of the box:
698
+ ### File Uploads
194
699
 
195
- ```plainscript
196
- remember encoded as jsonEncode(user)
197
- remember decoded as jsonDecode(encoded)
198
- remember contents as readFile("notes.txt")
199
- writeFile("notes.txt", contents)
200
- remember digest as sha256("plain text")
201
- remember currentTime as time()
202
- remember identifier as uuid()
203
700
  ```
701
+ accept uploads limit "5 MB" allow list with "image/png", "image/jpeg" folder "uploads"
204
702
 
205
- Other built-in helpers cover strings, collections, file paths, HTTP, caching, environment variables, and crypto.
703
+ route post "/scan"
704
+ let file be upload("doc")
705
+ ocr path of file as text
706
+ show "scanned: " + text
707
+ done
708
+ ```
206
709
 
207
- ## Images and visualizations
710
+ Files arrive as records with `name`, `type`, `size`, `data` (buffer), and `path` (string, when a folder is set). Oversized files return HTTP 413; wrong types return 415. `uploads("docs")` returns every file under a field name.
208
711
 
209
- PlainScript includes a dependency-free SVG image library. Use `barChart` or
210
- `lineChart` to turn labels and numbers into an image, then save it as an SVG or
211
- embed it in a web response with `imageDataUri`:
712
+ ### Rate Limiting
212
713
 
213
- ```plainscript
214
- remember months as ["Jan", "Feb", "Mar", "Apr"]
215
- remember signups as [12, 18, 27, 35]
714
+ ```
715
+ rate limit 100 requests per minute
716
+ ```
717
+
718
+ Sliding window per client IP; the quota-exceeded response is HTTP 429.
719
+
720
+ ### Google OAuth
721
+
722
+ ```
723
+ google oauth
724
+ id is env("GOOGLE_ID")
725
+ secret is env("GOOGLE_SECRET")
726
+ callback is "https://myapp.dev/auth/google/callback"
727
+ landing is "/dashboard"
728
+ done
729
+ ```
730
+
731
+ Registers `/auth/google` (redirect) and `/auth/google/callback` (code-for-token exchange plus profile fetch). After login, the session holds the user and the browser lands on `landing`.
732
+
733
+ ### Error Handling &amp; Retries
734
+
735
+ ```
736
+ try
737
+ let data be jsonDecode(raw)
738
+ recover as err
739
+ show "bad json: " + message of err
740
+ done
741
+
742
+ retry 3 times every 5 seconds
743
+ wait for fetch("https://flaky.api")
744
+ done
745
+ ```
746
+
747
+ Custom 404 handling:
748
+
749
+ ```
750
+ when nothing matches
751
+ status 404
752
+ show json
753
+ error is "No such road"
754
+ done
755
+ done
756
+ ```
757
+
758
+ ---
759
+
760
+ ## Runtime Standard Library
761
+
762
+ No imports needed - these functions are built into the compiler. They are the
763
+ standard vocabulary of everyday work - JSON, files, time, strings - so the
764
+ first version of a program usually needs no dependency at all:
765
+
766
+ | PlainScript | Description |
767
+ |---|---|
768
+ | `show(x)` | Print a value (`console.log`) |
769
+ | `readFile("path")` | Read a file as UTF-8 text |
770
+ | `writeFile("path", data)` | Write text to a file |
771
+ | `read("path")` | Read a file as UTF-8 text |
772
+ | `fileExists("path")` | Check if a file exists |
773
+ | `sleep(ms)` | Sleep synchronously |
774
+ | `time()` | Current Unix timestamp (`Date.now()`) |
775
+ | `date()` | ISO date string |
776
+ | `jsonEncode(value)` | `JSON.stringify` |
777
+ | `jsonDecode(string)` | `JSON.parse` |
778
+ | `env("KEY")` | Read environment variable |
779
+ | `exit(code)` | Exit the process |
780
+ | `uuid()` | Generate a UUID v4 |
781
+ | `length(x)` | Length of array/string |
782
+ | `uppercase(x)` | Convert to uppercase |
783
+ | `lowercase(x)` | Convert to lowercase |
784
+ | `random()` | Random number 0–1 |
785
+ | `round(x)` | Round to nearest integer |
786
+
787
+ ---
788
+
789
+ ## Web Applications
790
+
791
+ `web app` starts the HTTP stack available to every program. `route <method>
792
+ "<path>" ... done` registers an endpoint; `reply` (or `show`) sends a response,
793
+ `reply json ... done` sends JSON with `is`-style fields, and `start <port>`
794
+ serves it. `status <n>` sets the response code and `when nothing matches`
795
+ handles otherwise-unmatched requests.
796
+
797
+ ```
798
+ web app
799
+
800
+ route "/"
801
+ show "Hello from PlainScript!"
802
+ done
216
803
 
217
- remember chart as barChart("Monthly signups", months, signups, {
218
- width: 720,
219
- height: 420,
220
- accent: "#40c463"
221
- })
804
+ route "/api/status"
805
+ show json
806
+ status is "ok"
807
+ version is "2.0"
808
+ done
809
+ done
222
810
 
223
- saveImage("dist/monthly-signups.svg", chart)
224
- show "Saved dist/monthly-signups.svg"
811
+ start 3000
225
812
  ```
226
813
 
227
- Use `lineChart(title, labels, values, options)` for trends, `svgImage(width,
228
- height, markup, options)` for custom SVG content, and `imageDataUri(image)` when
229
- an image needs to be returned from a route or embedded in HTML. The generated
230
- image is a string, so it works with `saveImage`, `reply`, and normal string
231
- helpers without a native graphics dependency.
814
+ ---
232
815
 
233
- ![Example PlainScript visualization](docs/visualization-example.svg)
816
+ ## Browser games and interactive apps
234
817
 
235
- ## Web apps
818
+ The same `.pln` you run on Node compiles to a browser script. Drive a canvas,
819
+ handle keyboard, pointer, touch, and gamepad input, run `requestAnimationFrame`
820
+ loops with delta time, load images and audio, and call any JavaScript library
821
+ (Three.js, WebGL, WebGPU, Matter.js) through plain interop - no bundler needed:
236
822
 
237
823
  ```plainscript
238
824
  web app
825
+ serve folder "public"
826
+ route get "/"
827
+ reply file "public/index.html"
828
+ done
829
+ start 8000
830
+ ```
831
+
832
+ ```plainscript
833
+ remember canvas as document.getElementById("game")
834
+ remember ctx as canvas.getContext("2d")
835
+ remember keys as {}
836
+
837
+ when document "keydown" happens as ke
838
+ keys[ke.key] becomes true
839
+ done
840
+
841
+ if keys["ArrowLeft"] is true
842
+ ctx.fillStyle becomes "#40c463"
843
+ ctx.fillRect(20, 20, 40, 40)
844
+ done
845
+ ```
846
+
847
+ `when <target> "<event>" happens` maps to `addEventListener`. Browser builtins
848
+ (`select`, `selectAll`, `parseHTML`, `loadImage`, `loadAudio`, `fetchJson`,
849
+ `fetchBytes`, `readDataUrl`, `audioContext`/`playTone`, `localPoint`,
850
+ `gamepads`, `droppedFiles`, `webSocketSend`, and the WebGL helpers
851
+ `webglContext`/`glShader`/`glProgram`/`glBuffer`) make canvas apps, games, and
852
+ DOM UI direct. The full browser
853
+ and game development guide - input, loops, assets, audio, state, collision,
854
+ networking, persistence, and interop - is [docs/GAME-PROMPT.md](docs/GAME-PROMPT.md).
855
+
856
+ ## Additional Backend Capabilities
857
+
858
+ ### HTTP Routing
859
+
860
+ ```
861
+ web app
239
862
  allow cors
240
863
 
241
- route get "/health"
242
- reply json
243
- ok is true
864
+ group "/api"
865
+
866
+ route get "/users"
867
+ let users be query
868
+ SELECT * FROM users
869
+ done
870
+ show users
244
871
  done
872
+
873
+ route post "/users"
874
+ let missing be validate(body of request, list with "name", "email")
875
+ when length of missing is greater than 0
876
+ status 400
877
+ show missing
878
+ otherwise
879
+ show "created"
880
+ done
881
+ done
882
+
245
883
  done
246
884
 
247
- route post "/echo"
248
- remember body as body of request
249
- reply json
250
- received is body
885
+ start env("PORT")
886
+ ```
887
+
888
+ `param("id")`, `query("page")`, and `header("x-token")` read request data; `body()` / `body("field")` read the JSON request body; `group` composes path prefixes; `status <n>` sets the response code and `redirect to "<url>"` issues a redirect.
889
+
890
+ ### Transactions
891
+
892
+ ```
893
+ database "app.db" // or: postgres env("DATABASE_URL")
894
+
895
+ transaction
896
+ insert
897
+ INSERT INTO users (name) VALUES ({who})
251
898
  done
252
899
  done
900
+ ```
901
+
902
+ Placeholders `{likeThis}` bind to PlainScript variables. `postgres "..."` switches every SQL statement to node-postgres pool queries (`$n`, awaited).
903
+
904
+ ### Email
253
905
 
254
- start 3000
255
906
  ```
907
+ mail transport
908
+ host is "smtp.gmail.com"
909
+ port is 587
910
+ user is env("EMAIL_USER")
911
+ pass is env("EMAIL_PASS")
912
+ done
256
913
 
257
- Routes support `get`, `post`, `put`, `patch`, and `delete`. Read request data with `body of request`, `param("id")`, `query("page")`, and `header("x-name")`.
914
+ send mail
915
+ from is "hello@plainscript.dev"
916
+ to is "you@example.com"
917
+ subject is "Hello from PlainScript"
918
+ text is "Sent from a PlainScript program."
919
+ done
920
+ ```
258
921
 
259
- ## HTTP client
922
+ ### Cron &amp; Background Jobs
260
923
 
261
- ```plainscript
262
- remember response as get "https://example.com/data" timeout 5000
263
- remember created as post "https://example.com/data" with {name: "Ada"} headers {contentType: "application/json"}
264
- show response.status
265
924
  ```
925
+ every 5 minutes
926
+ show "heartbeat"
927
+ done
266
928
 
267
- ## SQLite
929
+ schedule "0 2 * * *"
930
+ show "nightly cleanup"
931
+ done
268
932
 
269
- ```plainscript
270
- database "app.db" using "wasm"
271
- remember name as "Ada"
933
+ to resize name
934
+ show `resizing ${name}`
935
+ done
936
+
937
+ run background resize("photo.png")
938
+ ```
939
+
940
+ ### WebSockets
272
941
 
273
- execute
274
- CREATE TABLE IF NOT EXISTS people (name TEXT, age INTEGER)
942
+ ```
943
+ websocket server on 8080
944
+ when socket connects
945
+ send socket "Welcome!"
946
+ done
947
+ when socket sends message
948
+ broadcast message
949
+ done
275
950
  done
951
+ ```
952
+
953
+ ### Cache
954
+
955
+ Redis-backed, with an in-memory fallback:
956
+
957
+ ```
958
+ cache env("REDIS_URL") // omit for an in-memory Map store with TTL
959
+ let token be cacheGet("token")
960
+ cacheSet("greeting", "hi", 60)
961
+ cacheDelete("greeting")
962
+ ```
963
+
964
+ Without a configured Redis instance, `cacheGet` / `cacheSet` / `cacheDelete` transparently fall back to an in-memory store, so naive caching works out of the box.
965
+
966
+ ### AI / ML
967
+
968
+ ```
969
+ let reply be chat("gpt-4o-mini", list with
970
+ record with role "user" and content "Say hello in two words"
971
+ done)
972
+
973
+ let vec be embedText("text-embedding-3-small", "PlainScript rocks")
974
+ let score be similarity(vec, embedText("text-embedding-3-small", "I love PlainScript"))
276
975
 
277
- insert
278
- INSERT INTO people (name, age) VALUES ({name}, 36)
976
+ let tags be ai_tags("PlainScript is an intent-oriented language")
977
+ let article be ai_post("Welcome to PlainScript", list with "why IOPL", "quick start")
978
+ ```
979
+
980
+ `chat` and `embedText` are async, OpenAI-compatible calls (from `OPENAI_API_KEY`, overridable with `options.apiKey` / `options.baseURL`); `similarity` returns a value in the range -1 to 1.
981
+
982
+ ### Pagination
983
+
984
+ ```
985
+ let page be paginate(allUsers, 2, 10)
986
+ show page.items # second page of 10
987
+ show page.hasNext # true if another page exists
988
+ ```
989
+
990
+ `paginate(list, page, perPage)` returns `record with items, count, page, pages, perPage, hasNext, hasPrev done`.
991
+
992
+ ---
993
+
994
+ ## Multi-File Projects
995
+
996
+ Programs grow into files. `import "./math.pln"` pulls a whole file into the
997
+ current one, `import { circleArea } from "./math.pln"` and `bring circleArea
998
+ from "./math.pln"` import specific names, and `export <name>` (or
999
+ `export <name> and <name>`) makes names available to other files:
1000
+
1001
+ ```
1002
+ import "./math.pln"
1003
+ import "./utils.pln"
1004
+ import { circleArea } from "./math.pln"
1005
+ bring circleArea from "./math.pln"
1006
+
1007
+ show PI
1008
+
1009
+ show double(5)
1010
+ ```
1011
+
1012
+ ```
1013
+ remember PI as 3.14159
1014
+ make circleArea(r)
1015
+ give PI * r * r
279
1016
  done
1017
+ export circleArea
1018
+ ```
1019
+
1020
+ Imports are bundled per entry: `plainscript build` gives every source file its own standalone output under `dist/`, with imported code inlined. Functions, lambdas, records, and modules together are how you build your own vocabulary on top of the core verbs - a new reader puzzle (`validate(body, fields)`) is a one-line call, not a loop.
280
1021
 
281
- remember people as query
282
- SELECT name, age FROM people
1022
+ ---
1023
+
1024
+ ## Express Integration
1025
+
1026
+ ```
1027
+ use express
1028
+
1029
+ let app be express()
1030
+
1031
+ serve folder "public"
1032
+
1033
+ when someone visits "/"
1034
+ show "Hello from PlainScript!"
1035
+ done
1036
+
1037
+ when someone visits "/api/status"
1038
+ show json
1039
+ status is "ok"
1040
+ version is "0.3"
1041
+ done
1042
+ done
1043
+
1044
+ listen on 3000
1045
+ show "Server running at http://localhost:3000"
283
1046
  done
284
1047
  ```
285
1048
 
286
- Use `using "native"` for a Node.js SQLite backend, or `using "wasm"` for in-memory. SQL placeholders like `{name}` bind to PlainScript variables.
1049
+ ---
287
1050
 
288
- ## Errors, async, and concurrency
1051
+ ## WhatsApp Bots
289
1052
 
290
- ```plainscript
291
- try
292
- remember result as get "https://example.com" timeout 5000
293
- recover as error
294
- show message of error
295
- finally
296
- show "finished"
1053
+ Full WhatsApp connectivity through Baileys - the implementation package is installed automatically and never appears in source:
297
1054
 
298
- retry 3 times every 1 second
299
- show "attempt"
1055
+ ```
1056
+ whatsapp bot
1057
+ auth "session" // credential folder, persists
1058
+ // across restarts
1059
+ login qr // or: login pairing "2348012345678"
1060
+
1061
+ on message
1062
+ log message // print the normalized record
1063
+
1064
+ when message.text is "/start"
1065
+ show "Welcome!"
1066
+ done
1067
+
1068
+ when message.text is "/help"
1069
+ show `Available commands:
1070
+ /start /help`
1071
+ done
1072
+ done
300
1073
  done
301
1074
  ```
302
1075
 
303
- Run promises in parallel with `allOf()`, `anyOf()`, and `settledOf()`. Schedule recurring work with `every 5 minutes ... done`.
1076
+ - `login qr` prints a scannable QR code; `login pairing "<number>"` prints an enter-on-phone code instead. Pairing numbers are validated at compile time (digits only after normalization, 8–15 characters).
1077
+ - `login pairing` also accepts a variable - prompt for the number at runtime instead of hard-coding it:
304
1078
 
305
- ## Testing
1079
+ ```
1080
+ ask "WhatsApp number: " as phone
306
1081
 
307
- ```plainscript
308
- test "addition works"
309
- check add(2, 3) equals 5
1082
+ whatsapp bot
1083
+ auth "session"
1084
+ login pairing phone
310
1085
  done
311
1086
  ```
312
1087
 
313
- Assertions: `equals`, `is`, `contains`, and `raises`.
1088
+ - Inside `on message`, `message` holds `record with text, chat, sender, name, id, time, isGroup done`; `print` answers the current chat.
1089
+ - The bot ignores its own messages and status broadcasts and keeps working in groups; transient disconnects reconnect after 3 seconds.
1090
+
1091
+ See [`examples/whatsapp-bot/`](./examples/whatsapp-bot/) for ready-to-link programs.
314
1092
 
315
- ## Examples
1093
+ ---
316
1094
 
317
- The `examples/` folder has working code for every feature:
1095
+ ## Supported Packages
318
1096
 
319
- | Topic | Files |
320
- | --- | --- |
321
- | Basics | `examples/basics.pln`, `examples/conditions.pln` |
322
- | Loops, functions, records | `examples/loops.pln`, `examples/functions.pln`, `examples/records.pln` |
323
- | Natural string verbs | `examples/string-verbs.pln` |
324
- | JSON, files, HTTP | `examples/json.pln`, `examples/files.pln`, `examples/http.pln` |
325
- | Database, web routes | `examples/sqlite.pln`, `examples/web-api.pln` |
326
- | Auth and sessions | `examples/auth-sessions.pln` |
327
- | Async and errors | `examples/async-errors.pln`, `examples/concurrency.pln` |
328
- | WebSockets, cache | `examples/websocket.pln`, `examples/cache-schedule.pln` |
329
- | Bots | `examples/bots.pln`, `examples/telegram-bot.pln`, `examples/whatsapp-bot/` |
330
- | OCR, uploads | `examples/ocr.pln`, `examples/id-verification/` |
331
- | Images, visualizations | `examples/visualization.pln` |
332
- | Tests, modules | `examples/testing.pln`, `examples/modules/` |
333
- | Starter projects | `templates/` |
1097
+ | PlainScript | Compiles to |
1098
+ |---|---|
1099
+ | `use express` | `const express = require('express');` |
1100
+ | `use sqlite` | `const Database = require('better-sqlite3');` |
1101
+ | `use fs` | `const fs = require('fs');` |
1102
+ | `use path` | `const path = require('path');` |
334
1103
 
335
- ## Project structure
1104
+ Any npm package can be used, including hyphenated names like `node-fetch` and scoped packages like `@scope/package-name`.
336
1105
 
337
- ```text
338
- compiler/ compiler, parser, and CLI
339
- examples/ feature demos and examples
340
- tests/ test suite
341
- docs/ website and docs
342
- plainscript-vscode/ VS Code extension
343
- editors/mt-manager/ TextMate grammar
1106
+ ---
1107
+
1108
+ ## Project Structure
1109
+
1110
+ ```
1111
+ plainscript/
1112
+ ├── compiler/
1113
+ │ ├── lexer.js tokenises PlainScript source into tokens
1114
+ │ ├── parser.js builds an AST from tokens
1115
+ │ ├── generator.js generates JavaScript from the AST
1116
+ │ ├── bundler.js resolves imports and bundles files
1117
+ │ ├── formatter.js normalises PlainScript source style
1118
+ │ ├── dependency-detector.js detects npm packages from source
1119
+ │ ├── version.js single compiler version constant
1120
+ │ └── cli.js command-line entry point
1121
+ │
1122
+ ├── examples/
1123
+ │ ├── hello.pln
1124
+ │ ├── day2.pln
1125
+ │ ├── day3.pln
1126
+ │ ├── arrays.pln
1127
+ │ ├── objects.pln
1128
+ │ ├── loops.pln
1129
+ │ ├── expressions.pln
1130
+ │ ├── stdlib.pln
1131
+ │ ├── server.pln
1132
+ │ ├── web-app.pln
1133
+ │ ├── start.pln
1134
+ │ ├── database.pln
1135
+ │ ├── deployment.pln
1136
+ │ ├── football-backend/ acceptance example (SQLite + auth + sessions)
1137
+ │ │ └── app.pln
1138
+ │ ├── id-verification/ acceptance example (uploads + OCR matching)
1139
+ │ │ ├── app.pln
1140
+ │ │ └── make-sample-id.js
1141
+ │ └── whatsapp-bot/ WhatsApp bots (QR and pairing linking)
1142
+ │ ├── qr.pln
1143
+ │ └── pairing.pln
1144
+ │
1145
+ ├── tests/
1146
+ │ ├── compiler.test.js language, CLI, and formatter coverage
1147
+ │ ├── build.test.js build model, config, and packaging coverage
1148
+ │ ├── backend.test.js web/database/email/cache runtime tests
1149
+ │ ├── telegram.test.js Telegram bot runtime tests
1150
+ │ ├── ocr.test.js OCR statement tests
1151
+ │ ├── runtime.test.js uploads, database, and bot feature suite
1152
+ │ ├── whatsapp.test.js WhatsApp bot runtime tests
1153
+ │ └── acceptance.test.js boots the example projects over live HTTP
1154
+ │
1155
+ ├── docs/
1156
+ │ ├── PLAINSCRIPT-SPEC.md
1157
+ │ └── index.html
1158
+ │
1159
+ ├── editors/
1160
+ │ └── mt-manager/
1161
+ │ └── plainscript.mtsx MT Manager syntax highlighting
1162
+ │
1163
+ ├── package.json
1164
+ └── README.md
344
1165
  ```
1166
+
1167
+ ---
1168
+
1169
+ ## Running the Tests
1170
+
1171
+ ```bash
1172
+ npm test
1173
+ ```
1174
+
1175
+ ---
1176
+
1177
+ ## Contributing
1178
+
1179
+ Contributions are welcome. Please read [`CONTRIBUTION.md`](./CONTRIBUTION.md) before opening a pull request, and check [`CHANGELOG.md`](./CHANGELOG.md) / [`RELEASE_NOTES.md`](./RELEASE_NOTES.md) for context on recent changes.
1180
+
1181
+ 1. Fork the repository and create a branch from `main`.
1182
+ 2. Make your changes, with tests where applicable (`npm test`).
1183
+ 3. Open a pull request describing the change and its motivation.
1184
+
1185
+ ---
1186
+
1187
+ ## License
1188
+
1189
+ Released under the [MIT License](./LICENSE).
1190
+
1191
+ <div align="center">
1192
+
1193
+ <sub>"When even a simple sentence can be code."</sub>
1194
+
1195
+ </div>