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.
- package/README.md +1052 -201
- package/compiler/bundler.js +4 -4
- package/compiler/cli.js +82 -18
- package/compiler/dependency-detector.js +34 -22
- package/compiler/generator.js +587 -172
- package/compiler/lexer.js +61 -39
- package/compiler/parser.js +685 -182
- package/compiler/sourcemap.js +1 -1
- package/compiler/version.js +1 -1
- package/docs/CAPABILITY_GAP_AUDIT.md +25 -4
- package/docs/FB-PROMPT.md +524 -0
- package/docs/GAME-PROMPT.md +916 -0
- package/docs/PLAINSCRIPT-SPEC.md +135 -5
- package/docs/index.html +28 -14
- package/docs/website/script.js +1 -1
- package/docs/website/style.css +162 -195
- package/examples/ai-providers.pln +1 -1
- package/examples/arrays.pln +1 -1
- package/examples/async-errors.pln +2 -1
- package/examples/auth-api.pln +1 -1
- package/examples/auth-sessions.pln +1 -1
- package/examples/basics.pln +1 -1
- package/examples/bots.pln +1 -1
- package/examples/browser-interactive/README.md +29 -0
- package/examples/browser-interactive/public/index.html +83 -0
- package/examples/browser-interactive/public/interactive.js +27 -0
- package/examples/browser-interactive/src/interactive.pln +34 -0
- package/examples/cache-and-jobs.pln +1 -1
- package/examples/cache-schedule.pln +1 -1
- package/examples/canvas-game/README.md +34 -0
- package/examples/canvas-game/public/game.js +131 -0
- package/examples/canvas-game/public/index.html +48 -0
- package/examples/canvas-game/src/game.pln +139 -0
- package/examples/collections.pln +1 -1
- package/examples/concurrency.pln +1 -1
- package/examples/conditions.pln +1 -1
- package/examples/database.pln +1 -1
- package/examples/day2.pln +1 -1
- package/examples/day3.pln +1 -1
- package/examples/deployment.pln +1 -1
- package/examples/email-send.pln +1 -1
- package/examples/error-handling.pln +3 -2
- package/examples/expressions.pln +1 -1
- package/examples/file-uploads.pln +1 -1
- package/examples/files-and-config.pln +1 -1
- package/examples/files.pln +1 -1
- package/examples/football-backend/app.pln +1 -1
- package/examples/functions.pln +1 -1
- package/examples/hello.pln +1 -1
- package/examples/http-client.pln +1 -1
- package/examples/http.pln +1 -1
- package/examples/id-verification/app.pln +1 -1
- package/examples/javascript-library/README.md +54 -0
- package/examples/javascript-library/package-lock.json +21 -0
- package/examples/javascript-library/package.json +8 -0
- package/examples/javascript-library/public/config.json +4 -0
- package/examples/javascript-library/public/index.html +40 -0
- package/examples/javascript-library/src/interop.pln +53 -0
- package/examples/json.pln +1 -1
- package/examples/loops.pln +1 -1
- package/examples/modules/app.pln +1 -1
- package/examples/modules/main.pln +1 -1
- package/examples/modules/math.pln +1 -1
- package/examples/mongo.pln +1 -1
- package/examples/objects.pln +1 -1
- package/examples/ocr.pln +1 -1
- package/examples/packages.pln +1 -1
- package/examples/record-kinds.pln +1 -1
- package/examples/records.pln +1 -1
- package/examples/rest-api-fetch.pln +1 -1
- package/examples/rest-api.pln +1 -1
- package/examples/scheduled-tasks.pln +1 -1
- package/examples/search-and-filter.pln +1 -1
- package/examples/server.pln +1 -1
- package/examples/sessions-and-cookies.pln +1 -1
- package/examples/sqlite.pln +1 -1
- package/examples/start.pln +1 -1
- package/examples/stdlib.pln +1 -1
- package/examples/string-verbs.pln +1 -1
- package/examples/telegram-ai-bot.pln +1 -1
- package/examples/telegram-bot.pln +1 -1
- package/examples/testing.pln +1 -1
- package/examples/three-dimensional/README.md +51 -0
- package/examples/three-dimensional/public/index.html +33 -0
- package/examples/three-dimensional/src/scene.pln +34 -0
- package/examples/web-api.pln +1 -1
- package/examples/web-app.pln +1 -1
- package/examples/websocket-server.pln +1 -1
- package/examples/websocket.pln +1 -1
- package/examples/whatsapp-bot/pairing.pln +2 -2
- package/examples/whatsapp-bot/qr.pln +2 -2
- 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
|
[](https://github.com/ayoistooslick/plainscript/actions/workflows/npm-publish.yml)
|
|
11
|
+
[](https://www.npmjs.com/package/plainscript-lang)
|
|
12
|
+
[](https://www.npmjs.com/package/plainscript-lang)
|
|
13
|
+
[](./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 & 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 & Objects](#arrays--objects)
|
|
39
|
+
- [Dictionaries, Sets & 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 & More](#record-kinds-concurrency--more)
|
|
45
|
+
- [Backend Services](#backend-services)
|
|
46
|
+
- [Databases](#databases)
|
|
47
|
+
- [HTTP Client](#http-client)
|
|
48
|
+
- [Authentication](#authentication)
|
|
49
|
+
- [Sessions & Cookies](#sessions--cookies)
|
|
50
|
+
- [File Uploads](#file-uploads)
|
|
51
|
+
- [Rate Limiting](#rate-limiting)
|
|
52
|
+
- [Google OAuth](#google-oauth)
|
|
53
|
+
- [Error Handling & 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 & 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
|
-
|
|
121
|
+
</td>
|
|
122
|
+
</tr>
|
|
123
|
+
</table>
|
|
6
124
|
|
|
7
|
-
|
|
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
|
|
11
|
-
cd
|
|
12
|
-
npm install
|
|
13
|
-
|
|
14
|
-
npm
|
|
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
|
-
|
|
139
|
+
Adding PlainScript to an existing project:
|
|
19
140
|
|
|
20
141
|
```bash
|
|
21
|
-
|
|
142
|
+
npm install --save-dev plainscript-lang
|
|
143
|
+
# start writing src/*.pln files - plainscript build auto-discovers them
|
|
22
144
|
```
|
|
23
145
|
|
|
24
|
-
|
|
146
|
+
No global install is required. Everything runs through `npm` scripts and `npx`.
|
|
147
|
+
|
|
148
|
+
### Supported Node.js and dependency policy
|
|
25
149
|
|
|
26
|
-
|
|
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
|
-
|
|
153
|
+
```bash
|
|
154
|
+
npm ci
|
|
155
|
+
```
|
|
41
156
|
|
|
42
|
-
|
|
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
|
-
|
|
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
|
-
|
|
48
|
-
|
|
49
|
-
|
|
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 & 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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
59
|
-
|
|
60
|
-
|
|
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 "
|
|
303
|
+
show "Teenager"
|
|
63
304
|
done
|
|
64
|
-
```
|
|
65
305
|
|
|
66
|
-
|
|
306
|
+
when name contains "PlainScript"
|
|
307
|
+
show "Found it"
|
|
308
|
+
done
|
|
67
309
|
|
|
68
|
-
|
|
310
|
+
when score between 90 and 100
|
|
311
|
+
show "A grade"
|
|
312
|
+
done
|
|
313
|
+
```
|
|
69
314
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
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 && <= 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
|
-
|
|
75
|
-
|
|
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
|
-
|
|
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
|
-
```
|
|
83
|
-
|
|
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
|
-
|
|
91
|
-
|
|
92
|
-
|
|
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 & 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
|
-
|
|
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
|
|
104
|
-
show
|
|
463
|
+
for every item in basket // alias for "for each"
|
|
464
|
+
show item
|
|
105
465
|
done
|
|
106
466
|
|
|
107
|
-
while
|
|
108
|
-
|
|
467
|
+
while age is less than 18
|
|
468
|
+
set age to age + 1
|
|
109
469
|
done
|
|
110
470
|
```
|
|
111
471
|
|
|
112
|
-
###
|
|
472
|
+
### Natural-Language Expressions
|
|
113
473
|
|
|
114
|
-
|
|
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 & 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
|
-
|
|
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
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
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 & processes | `args()`, `runCommand(cmd, [args])` |
|
|
597
|
+
| Filesystem & 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
|
-
|
|
132
|
-
remember
|
|
133
|
-
|
|
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
|
-
|
|
136
|
-
|
|
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
|
-
|
|
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
|
-
```
|
|
143
|
-
//
|
|
144
|
-
|
|
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
|
-
|
|
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
|
-
|
|
151
|
-
bring axios from "axios"
|
|
640
|
+
### HTTP Client
|
|
152
641
|
|
|
153
|
-
|
|
154
|
-
|
|
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
|
-
|
|
157
|
-
|
|
649
|
+
let created be post url with body
|
|
650
|
+
headers record with accept "application/json" done
|
|
651
|
+
timeout 5000
|
|
158
652
|
```
|
|
159
653
|
|
|
160
|
-
|
|
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
|
-
|
|
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
|
-
|
|
664
|
+
let payload be readToken(token, env("TOKEN_SECRET"))
|
|
665
|
+
```
|
|
174
666
|
|
|
175
|
-
|
|
667
|
+
`hashPassword` / `checkPassword` use scrypt; tokens are HMAC-signed with an expiry and fail closed on tampering or timeout.
|
|
176
668
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
669
|
+
### Sessions & 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
|
-
|
|
183
|
-
|
|
184
|
-
|
|
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
|
-
|
|
690
|
+
Sessions ride an HMAC-signed `HttpOnly` cookie (`plainscript.sid`). The store is in-memory: restarting the server signs everyone out.
|
|
190
691
|
|
|
191
|
-
|
|
692
|
+
```
|
|
693
|
+
set cookie "theme" to "dark" expires in 7 days
|
|
694
|
+
show cookie("theme")
|
|
695
|
+
clear cookie "theme"
|
|
696
|
+
```
|
|
192
697
|
|
|
193
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
```
|
|
214
|
-
|
|
215
|
-
|
|
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 & 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
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
804
|
+
route "/api/status"
|
|
805
|
+
show json
|
|
806
|
+
status is "ok"
|
|
807
|
+
version is "2.0"
|
|
808
|
+
done
|
|
809
|
+
done
|
|
222
810
|
|
|
223
|
-
|
|
224
|
-
show "Saved dist/monthly-signups.svg"
|
|
811
|
+
start 3000
|
|
225
812
|
```
|
|
226
813
|
|
|
227
|
-
|
|
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
|
-
|
|
816
|
+
## Browser games and interactive apps
|
|
234
817
|
|
|
235
|
-
|
|
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
|
-
|
|
242
|
-
|
|
243
|
-
|
|
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
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
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
|
-
|
|
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
|
-
|
|
922
|
+
### Cron & 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
|
-
|
|
929
|
+
schedule "0 2 * * *"
|
|
930
|
+
show "nightly cleanup"
|
|
931
|
+
done
|
|
268
932
|
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
933
|
+
to resize name
|
|
934
|
+
show `resizing ${name}`
|
|
935
|
+
done
|
|
936
|
+
|
|
937
|
+
run background resize("photo.png")
|
|
938
|
+
```
|
|
939
|
+
|
|
940
|
+
### WebSockets
|
|
272
941
|
|
|
273
|
-
|
|
274
|
-
|
|
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
|
-
|
|
278
|
-
|
|
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
|
-
|
|
282
|
-
|
|
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
|
-
|
|
1049
|
+
---
|
|
287
1050
|
|
|
288
|
-
##
|
|
1051
|
+
## WhatsApp Bots
|
|
289
1052
|
|
|
290
|
-
|
|
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
|
-
|
|
299
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1079
|
+
```
|
|
1080
|
+
ask "WhatsApp number: " as phone
|
|
306
1081
|
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
1082
|
+
whatsapp bot
|
|
1083
|
+
auth "session"
|
|
1084
|
+
login pairing phone
|
|
310
1085
|
done
|
|
311
1086
|
```
|
|
312
1087
|
|
|
313
|
-
|
|
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
|
-
|
|
1093
|
+
---
|
|
316
1094
|
|
|
317
|
-
|
|
1095
|
+
## Supported Packages
|
|
318
1096
|
|
|
319
|
-
|
|
|
320
|
-
|
|
321
|
-
|
|
|
322
|
-
|
|
|
323
|
-
|
|
|
324
|
-
|
|
|
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
|
-
|
|
1104
|
+
Any npm package can be used, including hyphenated names like `node-fetch` and scoped packages like `@scope/package-name`.
|
|
336
1105
|
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
plainscript
|
|
343
|
-
|
|
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>
|