plainscript-lang 0.1.7-latest
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/LICENSE +21 -0
- package/README.md +815 -0
- package/compiler/bundler.js +86 -0
- package/compiler/cli.js +843 -0
- package/compiler/dependency-detector.js +173 -0
- package/compiler/formatter.js +170 -0
- package/compiler/generator.js +2032 -0
- package/compiler/lexer.js +413 -0
- package/compiler/parser.js +2077 -0
- package/compiler/version.js +6 -0
- package/docs/PLINJS_SPEC.md +1051 -0
- package/docs/index.html +2287 -0
- package/docs/logo.jpg +0 -0
- package/docs/website/index.html +1500 -0
- package/docs/website/script.js +197 -0
- package/docs/website/style.css +1117 -0
- package/examples/arrays.pln +13 -0
- package/examples/cache-and-jobs.pln +29 -0
- package/examples/database.pln +41 -0
- package/examples/day2.pln +7 -0
- package/examples/day3.pln +11 -0
- package/examples/deployment.pln +12 -0
- package/examples/email-send.pln +22 -0
- package/examples/expressions.pln +40 -0
- package/examples/football-backend/app.pln +90 -0
- package/examples/hello.pln +3 -0
- package/examples/id-verification/app.pln +29 -0
- package/examples/id-verification/make-sample-id.js +123 -0
- package/examples/loops.pln +17 -0
- package/examples/objects.pln +12 -0
- package/examples/rest-api-fetch.pln +94 -0
- package/examples/rest-api.pln +68 -0
- package/examples/scheduled-tasks.pln +23 -0
- package/examples/server.pln +25 -0
- package/examples/start.pln +2 -0
- package/examples/stdlib.pln +41 -0
- package/examples/telegram-bot.pln +42 -0
- package/examples/web-app.pln +20 -0
- package/examples/websocket-server.pln +27 -0
- package/examples/whatsapp-bot/pairing.pln +17 -0
- package/examples/whatsapp-bot/qr.pln +8 -0
- package/package.json +47 -0
package/README.md
ADDED
|
@@ -0,0 +1,815 @@
|
|
|
1
|
+
# PlainScript
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<img src="docs/logo.jpg" alt="PlainScript Logo" width="200" />
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
> "When even a simple sentence can be code."
|
|
8
|
+
> Don't forget to star the repo
|
|
9
|
+
|
|
10
|
+
PlainScript is an Intent-Oriented Programming Language (IOPL). You describe **what** you want; the compiler decides **how** to implement it in JavaScript.
|
|
11
|
+
|
|
12
|
+
**Current version:** v0.1.7 — the `plainscript` npm package with a TypeScript-style production build (`plainscript build` → `dist/`, source names preserved).
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## Quick start
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npx plainscript new myapp # scaffolds src/app.pln and package.json
|
|
20
|
+
cd myapp
|
|
21
|
+
npm install # installs plainscript as a devDependency plus runtime packages
|
|
22
|
+
npm run build # compiles src/ -> dist/ (plainscript build)
|
|
23
|
+
node dist/app.js # or: npm start
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Adding PlainScript to an existing project:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
npm install --save-dev plainscript
|
|
30
|
+
# start writing src/*.pln files — plainscript build auto-discovers them
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
No global install is needed anywhere — everything runs through npm scripts
|
|
34
|
+
and `npx`.
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## CLI
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
plainscript run <file.pln> Install missing dependencies, compile and execute
|
|
42
|
+
(executes from a scratch dir — nothing is written
|
|
43
|
+
into your project)
|
|
44
|
+
plainscript build [file.pln] Compile to dist/. With no argument, builds every
|
|
45
|
+
.pln file under the source root, preserving names
|
|
46
|
+
and folder structure
|
|
47
|
+
plainscript check <file.pln> Check syntax only (no output, no execution)
|
|
48
|
+
plainscript fmt <file.pln> Format a PlainScript file in-place
|
|
49
|
+
plainscript new [name] Create a new PlainScript project (npm-ready)
|
|
50
|
+
plainscript install Install dependencies detected in the project's sources
|
|
51
|
+
plainscript start Build src/app.pln and run its dist/ output
|
|
52
|
+
plainscript doctor Check the PlainScript project environment
|
|
53
|
+
plainscript add <package> Install a package into the project
|
|
54
|
+
plainscript remove <package> Uninstall a package from the project
|
|
55
|
+
plainscript update Update all installed npm packages
|
|
56
|
+
plainscript version Print the compiler version
|
|
57
|
+
plainscript help Print help text
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## Building and configuration
|
|
63
|
+
|
|
64
|
+
`plainscript build` is a deterministic production build, TypeScript-style but for
|
|
65
|
+
`.pln` sources — **zero configuration required**:
|
|
66
|
+
|
|
67
|
+
- `plainscript build` (no argument) discovers every `.pln` file under `src/` and
|
|
68
|
+
compiles each to `dist/` **preserving source file names and folder structure**:
|
|
69
|
+
`src/messi.pln` → `dist/messi.js`,
|
|
70
|
+
`src/helpers/math.pln` → `dist/helpers/math.js`.
|
|
71
|
+
- `plainscript build <file.pln>` compiles a single file into `dist/`.
|
|
72
|
+
- Imports are bundled into each output, so every file in `dist/` runs
|
|
73
|
+
standalone under Node.
|
|
74
|
+
- Rebuilds are byte-identical — safe to commit, diff, and cache.
|
|
75
|
+
|
|
76
|
+
Source discovery skips `node_modules`, hidden directories, and the output
|
|
77
|
+
directory itself. When no `src/` directory exists, the project root is scanned
|
|
78
|
+
instead.
|
|
79
|
+
|
|
80
|
+
### Optional `plainscript.config.json`
|
|
81
|
+
|
|
82
|
+
For projects that need custom output or source directories, add a
|
|
83
|
+
`plainscript.config.json` with a `compilerOptions` block (like `tsconfig.json`):
|
|
84
|
+
|
|
85
|
+
```json
|
|
86
|
+
{
|
|
87
|
+
"compilerOptions": {
|
|
88
|
+
"outDir": "./build",
|
|
89
|
+
"rootDir": "./lib",
|
|
90
|
+
"exclude": ["vendor"]
|
|
91
|
+
}
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
| Key | Default | Meaning |
|
|
96
|
+
|-------------|----------------------------------|----------------------------------------------|
|
|
97
|
+
| `outDir` | `"dist"` | Build output directory |
|
|
98
|
+
| `rootDir` | `"src"` if it exists, else `"."` | Root that `plainscript build` scans for sources |
|
|
99
|
+
| `exclude` | `["node_modules"]` | Directories to skip during source discovery |
|
|
100
|
+
|
|
101
|
+
### Publishing a library written in PlainScript
|
|
102
|
+
|
|
103
|
+
```json
|
|
104
|
+
{
|
|
105
|
+
"name": "my-plainscript-library",
|
|
106
|
+
"main": "dist/index.js",
|
|
107
|
+
"scripts": {
|
|
108
|
+
"build": "plainscript build",
|
|
109
|
+
"prepare": "plainscript build"
|
|
110
|
+
},
|
|
111
|
+
"devDependencies": { "plainscript": "^0.1.7" }
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
`src/index.pln` builds to `dist/index.js`; consumers install and `require()`
|
|
116
|
+
it like any Node package. There is no PlainScript-specific registry or format —
|
|
117
|
+
standard `package.json` semantics apply.
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## Language features
|
|
122
|
+
|
|
123
|
+
### Variables
|
|
124
|
+
|
|
125
|
+
```plainscript
|
|
126
|
+
remember name as "Ayokunle"
|
|
127
|
+
remember age as 16
|
|
128
|
+
age becomes 17
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### String Templates
|
|
132
|
+
|
|
133
|
+
Backtick-delimited strings preserve whitespace and support `${expression}` interpolation:
|
|
134
|
+
|
|
135
|
+
```plainscript
|
|
136
|
+
remember name as "World"
|
|
137
|
+
remember greeting as `Hello ${name}!`
|
|
138
|
+
show greeting
|
|
139
|
+
|
|
140
|
+
remember email as `Dear ${customer},
|
|
141
|
+
|
|
142
|
+
Thank you for your order #${orderId}.
|
|
143
|
+
|
|
144
|
+
Best regards,
|
|
145
|
+
The Team`
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Interpolation compiles directly to JavaScript template literals — it is not evaluated at compile time. Literal dollar signs without `{` are preserved as-is.
|
|
149
|
+
|
|
150
|
+
### Conditions
|
|
151
|
+
|
|
152
|
+
```plainscript
|
|
153
|
+
if age is at least 18
|
|
154
|
+
show "Adult"
|
|
155
|
+
otherwise
|
|
156
|
+
show "Teenager"
|
|
157
|
+
done
|
|
158
|
+
|
|
159
|
+
if name contains "PlainScript"
|
|
160
|
+
show "Found it"
|
|
161
|
+
done
|
|
162
|
+
|
|
163
|
+
if score between 90 and 100
|
|
164
|
+
show "A grade"
|
|
165
|
+
done
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
All comparison operators:
|
|
169
|
+
|
|
170
|
+
| PlainScript | JavaScript |
|
|
171
|
+
|------------------------|--------------------|
|
|
172
|
+
| `is` / `is equal to` | `===` |
|
|
173
|
+
| `is not` | `!==` |
|
|
174
|
+
| `is greater than` / `is above` | `>` |
|
|
175
|
+
| `is less than` / `is below` | `<` |
|
|
176
|
+
| `is at least` | `>=` |
|
|
177
|
+
| `is at most` | `<=` |
|
|
178
|
+
| `is empty` | `.length === 0` |
|
|
179
|
+
| `is not empty` | `.length > 0` |
|
|
180
|
+
| `contains "x"` | `.includes("x")` |
|
|
181
|
+
| `starts with "x"` | `.startsWith("x")` |
|
|
182
|
+
| `ends with "x"` | `.endsWith("x")` |
|
|
183
|
+
| `between A and B` | `>= A && <= B` |
|
|
184
|
+
|
|
185
|
+
### Functions
|
|
186
|
+
|
|
187
|
+
```plainscript
|
|
188
|
+
make add(a, b)
|
|
189
|
+
give a + b
|
|
190
|
+
done
|
|
191
|
+
show add(5, 7)
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
### Arrays & Objects
|
|
195
|
+
|
|
196
|
+
```plainscript
|
|
197
|
+
remember players as ["Haaland", "Foden", "Rodri"]
|
|
198
|
+
show players[0]
|
|
199
|
+
players[1] becomes "Palmer"
|
|
200
|
+
|
|
201
|
+
remember user as
|
|
202
|
+
name is "Ayokunle"
|
|
203
|
+
age is 17
|
|
204
|
+
done
|
|
205
|
+
show user.name
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
### Loops
|
|
209
|
+
|
|
210
|
+
```plainscript
|
|
211
|
+
for each player in players
|
|
212
|
+
show player
|
|
213
|
+
done
|
|
214
|
+
|
|
215
|
+
for every item in basket // alias for "for each"
|
|
216
|
+
show item
|
|
217
|
+
done
|
|
218
|
+
|
|
219
|
+
while age is less than 18
|
|
220
|
+
age becomes age + 1
|
|
221
|
+
done
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
### PlainScript Expressions
|
|
225
|
+
|
|
226
|
+
Collections, properties, and files read like sentences.
|
|
227
|
+
|
|
228
|
+
**Items**
|
|
229
|
+
|
|
230
|
+
```plainscript
|
|
231
|
+
remember players as ["Haaland", "Foden", "Rodri"]
|
|
232
|
+
|
|
233
|
+
show first player from players // players[0]
|
|
234
|
+
show last player from players // players[players.length - 1]
|
|
235
|
+
show player two from players // players[1]
|
|
236
|
+
first player from players becomes "Haaland" // players[0] = "Haaland"
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
Number words from `one` to `twenty` map to one-based positions: `player one` is the first item.
|
|
240
|
+
|
|
241
|
+
**Collections**
|
|
242
|
+
|
|
243
|
+
```plainscript
|
|
244
|
+
show players length // players.length
|
|
245
|
+
add("Palmer" to players) // players.push("Palmer")
|
|
246
|
+
remove("Rodri" from players) // players.splice(players.indexOf("Rodri"), 1)
|
|
247
|
+
|
|
248
|
+
if players contains "Foden" // players.includes("Foden")
|
|
249
|
+
show "Found"
|
|
250
|
+
done
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
**Properties**
|
|
254
|
+
|
|
255
|
+
```plainscript
|
|
256
|
+
show name of user // user.name
|
|
257
|
+
show city of address of customer // customer.address.city
|
|
258
|
+
name of user becomes "Ayo" // user.name = "Ayo"
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
`of` chains right-to-left: `city of address of customer` reads the city of the address of the customer.
|
|
262
|
+
|
|
263
|
+
**Files**
|
|
264
|
+
|
|
265
|
+
```plainscript
|
|
266
|
+
remember data as read("users.txt") // fs.readFileSync("users.txt", 'utf8')
|
|
267
|
+
write(data to "users.txt") // fs.writeFileSync(data, "users.txt", 'utf8')
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
The older `readFile()` / `writeFile()` forms still work and are unchanged.
|
|
271
|
+
|
|
272
|
+
### JavaScript Gateway
|
|
273
|
+
|
|
274
|
+
JavaScript blocks run raw JavaScript with full async support:
|
|
275
|
+
|
|
276
|
+
```plainscript
|
|
277
|
+
remember response as javascript
|
|
278
|
+
const res = await fetch("https://api.example.com")
|
|
279
|
+
const data = await res.json()
|
|
280
|
+
return data
|
|
281
|
+
done
|
|
282
|
+
show response
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
`ask` reads a line of input from the terminal:
|
|
286
|
+
|
|
287
|
+
```plainscript
|
|
288
|
+
ask "What is your name?" as name
|
|
289
|
+
show "Hello, " + name
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
Any npm package can be declared with `use`:
|
|
293
|
+
|
|
294
|
+
```plainscript
|
|
295
|
+
use axios
|
|
296
|
+
use node-fetch
|
|
297
|
+
use @scope/package-name
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
---
|
|
301
|
+
|
|
302
|
+
## Backend Services
|
|
303
|
+
|
|
304
|
+
Everything below is compiled by the deterministic compiler — no rules, no AI,
|
|
305
|
+
no hidden codegen.
|
|
306
|
+
|
|
307
|
+
### Portable databases (SQLite native or WebAssembly)
|
|
308
|
+
|
|
309
|
+
```plainscript
|
|
310
|
+
database "app.db" // probes better-sqlite3, falls back to sql.js
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
`plainscript install` verifies that `better-sqlite3` actually loads; if the native
|
|
314
|
+
module cannot be used, PlainScript warns and continues on the pure-JavaScript
|
|
315
|
+
WebAssembly engine (`sql.js`) — the same program runs unchanged. Force an
|
|
316
|
+
engine explicitly:
|
|
317
|
+
|
|
318
|
+
```plainscript
|
|
319
|
+
database "app.db" using "native" // hard requirement: better-sqlite3
|
|
320
|
+
database "app.db" using "wasm" // hard requirement: sql.js
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
The WebAssembly engine persists the whole database to disk after every write,
|
|
324
|
+
so data survives restarts either way.
|
|
325
|
+
|
|
326
|
+
### HTTP client
|
|
327
|
+
|
|
328
|
+
```plainscript
|
|
329
|
+
remember r as get "https://api.example.com/users"
|
|
330
|
+
if ok of r
|
|
331
|
+
show status of r
|
|
332
|
+
show data of r
|
|
333
|
+
done
|
|
334
|
+
|
|
335
|
+
remember created as post url with body
|
|
336
|
+
headers { accept: "application/json" }
|
|
337
|
+
timeout 5000
|
|
338
|
+
```
|
|
339
|
+
|
|
340
|
+
Methods: `get`, `post … with <body>`, `put`, `patch`, `delete "<url>"`.
|
|
341
|
+
Responses are records: `ok`, `status`, `headers`, `data` (JSON is parsed
|
|
342
|
+
automatically). The default timeout is 30 seconds. `wait for fetch(...)`
|
|
343
|
+
awaits raw promises when you need it.
|
|
344
|
+
|
|
345
|
+
### Passwords and tokens (built-in auth)
|
|
346
|
+
|
|
347
|
+
```plainscript
|
|
348
|
+
remember hash as hashPassword("correct horse")
|
|
349
|
+
if checkPassword(password of body of request, hash)
|
|
350
|
+
remember token as createToken(user, env("TOKEN_SECRET"), 3600)
|
|
351
|
+
done
|
|
352
|
+
|
|
353
|
+
remember payload as readToken(token, env("TOKEN_SECRET"))
|
|
354
|
+
```
|
|
355
|
+
|
|
356
|
+
`hashPassword`/`checkPassword` use scrypt; tokens are HMAC-signed with an
|
|
357
|
+
expiry and fail closed on tampering or timeout.
|
|
358
|
+
|
|
359
|
+
### Sessions
|
|
360
|
+
|
|
361
|
+
```plainscript
|
|
362
|
+
web app
|
|
363
|
+
enable sessions "a-long-random-secret"
|
|
364
|
+
|
|
365
|
+
route post "/login"
|
|
366
|
+
user of session of request becomes username of body of request
|
|
367
|
+
reply "welcome"
|
|
368
|
+
done
|
|
369
|
+
|
|
370
|
+
route get "/me"
|
|
371
|
+
reply user of session of request
|
|
372
|
+
done
|
|
373
|
+
|
|
374
|
+
route post "/logout"
|
|
375
|
+
destroy session
|
|
376
|
+
reply "bye"
|
|
377
|
+
done
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
Sessions ride an HMAC-signed `HttpOnly` cookie (`plainscript.sid`). The store is
|
|
381
|
+
in-memory: restarting the server signs everyone out.
|
|
382
|
+
|
|
383
|
+
### File uploads
|
|
384
|
+
|
|
385
|
+
```plainscript
|
|
386
|
+
accept uploads limit "5 MB" allow ["image/png", "image/jpeg"] folder "uploads"
|
|
387
|
+
|
|
388
|
+
route post "/scan"
|
|
389
|
+
remember file as upload("doc")
|
|
390
|
+
ocr path of file as text
|
|
391
|
+
reply "scanned: " + text
|
|
392
|
+
done
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
Files arrive as records with `name`, `type`, `size`, `data` (buffer) and
|
|
396
|
+
`path` (string, when a folder is set). Oversized files get HTTP 413, wrong
|
|
397
|
+
types 415. `uploads("docs")` returns every file under a field name.
|
|
398
|
+
|
|
399
|
+
### Cookies
|
|
400
|
+
|
|
401
|
+
```plainscript
|
|
402
|
+
set cookie "theme" to "dark" expires in 7 days
|
|
403
|
+
show cookie("theme")
|
|
404
|
+
clear cookie "theme"
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
### Rate limiting
|
|
408
|
+
|
|
409
|
+
```plainscript
|
|
410
|
+
rate limit 100 requests per minute
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
Sliding window per client IP; the quota-exceeded response is HTTP 429.
|
|
414
|
+
|
|
415
|
+
### Google OAuth
|
|
416
|
+
|
|
417
|
+
```plainscript
|
|
418
|
+
google oauth
|
|
419
|
+
id is env("GOOGLE_ID")
|
|
420
|
+
secret is env("GOOGLE_SECRET")
|
|
421
|
+
callback is "https://myapp.dev/auth/google/callback"
|
|
422
|
+
landing is "/dashboard"
|
|
423
|
+
done
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
Registers `/auth/google` (redirect) and `/auth/google/callback`
|
|
427
|
+
(code-for-token exchange + profile fetch); after login the session holds the
|
|
428
|
+
user and the browser lands on `landing`.
|
|
429
|
+
|
|
430
|
+
### Custom 404
|
|
431
|
+
|
|
432
|
+
```plainscript
|
|
433
|
+
when nothing matches
|
|
434
|
+
status 404
|
|
435
|
+
reply json
|
|
436
|
+
error is "No such road"
|
|
437
|
+
done
|
|
438
|
+
done
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
### Error handling and retries
|
|
442
|
+
|
|
443
|
+
```plainscript
|
|
444
|
+
try
|
|
445
|
+
remember data as jsonDecode(raw)
|
|
446
|
+
recover as err
|
|
447
|
+
show "bad json: " + message of err
|
|
448
|
+
done
|
|
449
|
+
|
|
450
|
+
retry 3 times every 5 seconds
|
|
451
|
+
wait for fetch("https://flaky.api")
|
|
452
|
+
done
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
---
|
|
456
|
+
|
|
457
|
+
## Runtime Standard Library
|
|
458
|
+
|
|
459
|
+
No imports needed. These functions are built into the compiler:
|
|
460
|
+
|
|
461
|
+
| PlainScript | Description |
|
|
462
|
+
|--------------------------|------------------------------------|
|
|
463
|
+
| `print(x)` | Print a value (`console.log`) |
|
|
464
|
+
| `readFile("path")` | Read a file as UTF-8 text |
|
|
465
|
+
| `writeFile("path", data)` | Write text to a file |
|
|
466
|
+
| `read("path")` | Read a file as UTF-8 text |
|
|
467
|
+
| `fileExists("path")` | Check if a file exists |
|
|
468
|
+
| `sleep(ms)` | Sleep synchronously |
|
|
469
|
+
| `time()` | Current Unix timestamp (`Date.now()`) |
|
|
470
|
+
| `date()` | ISO date string |
|
|
471
|
+
| `jsonEncode(value)` | `JSON.stringify` |
|
|
472
|
+
| `jsonDecode(string)` | `JSON.parse` |
|
|
473
|
+
| `env("KEY")` | Read environment variable |
|
|
474
|
+
| `exit(code)` | Exit the process |
|
|
475
|
+
| `uuid()` | Generate a UUID v4 |
|
|
476
|
+
| `length(x)` | Length of array/string |
|
|
477
|
+
| `uppercase(x)` | Convert to uppercase |
|
|
478
|
+
| `lowercase(x)` | Convert to lowercase |
|
|
479
|
+
| `random()` | Random number 0–1 |
|
|
480
|
+
| `round(x)` | Round to nearest integer |
|
|
481
|
+
|
|
482
|
+
---
|
|
483
|
+
|
|
484
|
+
## Web Apps
|
|
485
|
+
|
|
486
|
+
```plainscript
|
|
487
|
+
web app
|
|
488
|
+
|
|
489
|
+
route "/"
|
|
490
|
+
reply "Hello from PlainScript!"
|
|
491
|
+
done
|
|
492
|
+
|
|
493
|
+
route "/api/status"
|
|
494
|
+
reply json
|
|
495
|
+
status is "ok"
|
|
496
|
+
version is "2.0"
|
|
497
|
+
done
|
|
498
|
+
done
|
|
499
|
+
|
|
500
|
+
start 3000
|
|
501
|
+
```
|
|
502
|
+
|
|
503
|
+
---
|
|
504
|
+
|
|
505
|
+
## SQLite Database
|
|
506
|
+
|
|
507
|
+
```plainscript
|
|
508
|
+
database "app.db"
|
|
509
|
+
|
|
510
|
+
execute
|
|
511
|
+
CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)
|
|
512
|
+
done
|
|
513
|
+
|
|
514
|
+
insert
|
|
515
|
+
INSERT INTO users (name) VALUES ('Alice')
|
|
516
|
+
done
|
|
517
|
+
|
|
518
|
+
remember rows as query
|
|
519
|
+
SELECT * FROM users
|
|
520
|
+
done
|
|
521
|
+
```
|
|
522
|
+
|
|
523
|
+
---
|
|
524
|
+
|
|
525
|
+
## Backend Capabilities
|
|
526
|
+
|
|
527
|
+
Everything a backend needs, as first-class deterministic language features —
|
|
528
|
+
no rules, no AI, no hidden codegen.
|
|
529
|
+
|
|
530
|
+
### HTTP routing
|
|
531
|
+
|
|
532
|
+
```plainscript
|
|
533
|
+
web app
|
|
534
|
+
allow cors
|
|
535
|
+
|
|
536
|
+
group "/api"
|
|
537
|
+
|
|
538
|
+
route get "/users"
|
|
539
|
+
remember users as query
|
|
540
|
+
SELECT * FROM users
|
|
541
|
+
done
|
|
542
|
+
reply users
|
|
543
|
+
done
|
|
544
|
+
|
|
545
|
+
route post "/users"
|
|
546
|
+
remember missing as validate(body of request, ["name", "email"])
|
|
547
|
+
if length(missing) is greater than 0
|
|
548
|
+
status 400
|
|
549
|
+
reply missing
|
|
550
|
+
otherwise
|
|
551
|
+
reply "created"
|
|
552
|
+
done
|
|
553
|
+
done
|
|
554
|
+
|
|
555
|
+
done
|
|
556
|
+
|
|
557
|
+
start env("PORT")
|
|
558
|
+
```
|
|
559
|
+
|
|
560
|
+
`param("id")`, `query("page")` and `header("x-token")` read request data;
|
|
561
|
+
`group` composes path prefixes; `status <n>` sets the response code.
|
|
562
|
+
|
|
563
|
+
### Databases with parameters and transactions
|
|
564
|
+
|
|
565
|
+
```plainscript
|
|
566
|
+
database "app.db" // or: postgres env("DATABASE_URL")
|
|
567
|
+
|
|
568
|
+
transaction
|
|
569
|
+
insert
|
|
570
|
+
INSERT INTO users (name) VALUES ({who})
|
|
571
|
+
done
|
|
572
|
+
done
|
|
573
|
+
```
|
|
574
|
+
|
|
575
|
+
Placeholders `{likeThis}` bind to PlainScript variables. `postgres "..."` switches
|
|
576
|
+
every SQL statement to node-postgres pool queries (`$n`, awaited).
|
|
577
|
+
|
|
578
|
+
### Email
|
|
579
|
+
|
|
580
|
+
```plainscript
|
|
581
|
+
mail transport
|
|
582
|
+
host is "smtp.gmail.com"
|
|
583
|
+
port is 587
|
|
584
|
+
user is env("EMAIL_USER")
|
|
585
|
+
pass is env("EMAIL_PASS")
|
|
586
|
+
done
|
|
587
|
+
|
|
588
|
+
send mail
|
|
589
|
+
from is "hello@plainscript.dev"
|
|
590
|
+
to is "you@example.com"
|
|
591
|
+
subject is "Hello from PlainScript"
|
|
592
|
+
text is "Sent from a PlainScript program."
|
|
593
|
+
done
|
|
594
|
+
```
|
|
595
|
+
|
|
596
|
+
### Cron and background jobs
|
|
597
|
+
|
|
598
|
+
```plainscript
|
|
599
|
+
every 5 minutes
|
|
600
|
+
show "heartbeat"
|
|
601
|
+
done
|
|
602
|
+
|
|
603
|
+
schedule "0 2 * * *"
|
|
604
|
+
show "nightly cleanup"
|
|
605
|
+
done
|
|
606
|
+
|
|
607
|
+
run background resizeImage("photo.png")
|
|
608
|
+
```
|
|
609
|
+
|
|
610
|
+
### WebSocket servers
|
|
611
|
+
|
|
612
|
+
```plainscript
|
|
613
|
+
websocket server on 8080
|
|
614
|
+
when socket connects
|
|
615
|
+
send socket "Welcome!"
|
|
616
|
+
done
|
|
617
|
+
when socket sends message
|
|
618
|
+
broadcast message
|
|
619
|
+
done
|
|
620
|
+
done
|
|
621
|
+
```
|
|
622
|
+
|
|
623
|
+
### Cache (Redis)
|
|
624
|
+
|
|
625
|
+
```plainscript
|
|
626
|
+
cache env("REDIS_URL")
|
|
627
|
+
remember token as cacheGet("token")
|
|
628
|
+
cacheSet("greeting", "hi", 60)
|
|
629
|
+
cacheDelete("greeting")
|
|
630
|
+
```
|
|
631
|
+
|
|
632
|
+
---
|
|
633
|
+
|
|
634
|
+
## Multi-file projects
|
|
635
|
+
|
|
636
|
+
```plainscript
|
|
637
|
+
import "./math.pln"
|
|
638
|
+
import "./utils.pln"
|
|
639
|
+
|
|
640
|
+
show PI
|
|
641
|
+
|
|
642
|
+
show double(5)
|
|
643
|
+
```
|
|
644
|
+
|
|
645
|
+
Imports are bundled per entry: `plainscript build` gives every source file its own
|
|
646
|
+
standalone output under `dist/`, with imported code inlined.
|
|
647
|
+
|
|
648
|
+
---
|
|
649
|
+
|
|
650
|
+
## Express server
|
|
651
|
+
|
|
652
|
+
```plainscript
|
|
653
|
+
use express
|
|
654
|
+
|
|
655
|
+
remember app as express()
|
|
656
|
+
|
|
657
|
+
serve folder "public"
|
|
658
|
+
|
|
659
|
+
when someone visits "/"
|
|
660
|
+
reply "Hello from PlainScript!"
|
|
661
|
+
done
|
|
662
|
+
|
|
663
|
+
when someone visits "/api/status"
|
|
664
|
+
reply json
|
|
665
|
+
status is "ok"
|
|
666
|
+
version is "0.3"
|
|
667
|
+
done
|
|
668
|
+
done
|
|
669
|
+
|
|
670
|
+
listen on 3000
|
|
671
|
+
show "Server running at http://localhost:3000"
|
|
672
|
+
done
|
|
673
|
+
```
|
|
674
|
+
|
|
675
|
+
---
|
|
676
|
+
|
|
677
|
+
## WhatsApp Bots
|
|
678
|
+
|
|
679
|
+
Full WhatsApp connectivity through Baileys — the implementation package is
|
|
680
|
+
installed automatically and never appears in your source:
|
|
681
|
+
|
|
682
|
+
```plainscript
|
|
683
|
+
whatsapp bot
|
|
684
|
+
auth "session" // credential folder, persists
|
|
685
|
+
// across restarts
|
|
686
|
+
login qr // or: login pairing "2348012345678"
|
|
687
|
+
|
|
688
|
+
on message
|
|
689
|
+
log message // print the normalized record
|
|
690
|
+
|
|
691
|
+
if message.text is "/start"
|
|
692
|
+
reply "Welcome!"
|
|
693
|
+
done
|
|
694
|
+
|
|
695
|
+
if message.text is "/help"
|
|
696
|
+
reply `Available commands:
|
|
697
|
+
/start /help`
|
|
698
|
+
done
|
|
699
|
+
done
|
|
700
|
+
done
|
|
701
|
+
```
|
|
702
|
+
|
|
703
|
+
- `login qr` prints a scannable QR code; `login pairing "<number>"` prints an
|
|
704
|
+
enter-on-phone code instead. Pairing numbers are validated at compile time
|
|
705
|
+
(digits only after normalization, 8–15).
|
|
706
|
+
- `login pairing` also accepts any value — prompt for the number
|
|
707
|
+
at runtime instead of hard-coding it:
|
|
708
|
+
|
|
709
|
+
```plainscript
|
|
710
|
+
ask "WhatsApp number: " as phone
|
|
711
|
+
|
|
712
|
+
whatsapp bot
|
|
713
|
+
auth "session"
|
|
714
|
+
login pairing phone
|
|
715
|
+
done
|
|
716
|
+
```
|
|
717
|
+
|
|
718
|
+
- Inside `on message`, `message` holds `{ text, chat, sender, name, id,
|
|
719
|
+
time, isGroup }`; `reply` answers the current chat.
|
|
720
|
+
- The bot ignores its own messages and status broadcasts and keeps working in
|
|
721
|
+
groups; transient disconnects reconnect after 3 seconds.
|
|
722
|
+
|
|
723
|
+
See `examples/whatsapp-bot/` for ready-to-link programs.
|
|
724
|
+
|
|
725
|
+
---
|
|
726
|
+
|
|
727
|
+
## Project management
|
|
728
|
+
|
|
729
|
+
```bash
|
|
730
|
+
plainscript install # Install all detected dependencies
|
|
731
|
+
plainscript add express # Add a package
|
|
732
|
+
plainscript remove express # Remove a package
|
|
733
|
+
plainscript update # Update all packages
|
|
734
|
+
plainscript start # Build src/app.pln and run its dist/ output
|
|
735
|
+
plainscript doctor # Check project environment
|
|
736
|
+
```
|
|
737
|
+
|
|
738
|
+
---
|
|
739
|
+
|
|
740
|
+
## Supported packages
|
|
741
|
+
|
|
742
|
+
| PlainScript | Compiles to |
|
|
743
|
+
|---------------------------|--------------------------------------|
|
|
744
|
+
| `use express` | `const express = require('express');` |
|
|
745
|
+
| `use sqlite` | `const Database = require('better-sqlite3');` |
|
|
746
|
+
| `use fs` | `const fs = require('fs');` |
|
|
747
|
+
| `use path` | `const path = require('path');` |
|
|
748
|
+
|
|
749
|
+
Any npm package can be used, including hyphenated names like `node-fetch` and
|
|
750
|
+
scoped packages like `@scope/package-name`.
|
|
751
|
+
|
|
752
|
+
---
|
|
753
|
+
|
|
754
|
+
## Running the tests
|
|
755
|
+
|
|
756
|
+
```bash
|
|
757
|
+
npm test
|
|
758
|
+
```
|
|
759
|
+
|
|
760
|
+
---
|
|
761
|
+
|
|
762
|
+
## Project structure
|
|
763
|
+
|
|
764
|
+
```
|
|
765
|
+
plainscript/
|
|
766
|
+
├── compiler/
|
|
767
|
+
│ ├── lexer.js — tokenises PlainScript source into tokens
|
|
768
|
+
│ ├── parser.js — builds an AST from tokens
|
|
769
|
+
│ ├── generator.js — generates JavaScript from the AST
|
|
770
|
+
│ ├── bundler.js — resolves imports and bundles files
|
|
771
|
+
│ ├── formatter.js — normalises PlainScript source style
|
|
772
|
+
│ ├── dependency-detector.js— detects npm packages from source
|
|
773
|
+
│ ├── version.js — single compiler version constant
|
|
774
|
+
│ └── cli.js — command-line entry point
|
|
775
|
+
│
|
|
776
|
+
├── examples/
|
|
777
|
+
│ ├── hello.pln
|
|
778
|
+
│ ├── day2.pln
|
|
779
|
+
│ ├── day3.pln
|
|
780
|
+
│ ├── arrays.pln
|
|
781
|
+
│ ├── objects.pln
|
|
782
|
+
│ ├── loops.pln
|
|
783
|
+
│ ├── expressions.pln
|
|
784
|
+
│ ├── stdlib.pln
|
|
785
|
+
│ ├── server.pln
|
|
786
|
+
│ ├── web-app.pln
|
|
787
|
+
│ ├── start.pln
|
|
788
|
+
│ ├── database.pln
|
|
789
|
+
│ ├── deployment.pln
|
|
790
|
+
│ ├── football-backend/ — acceptance example (SQLite + auth + sessions)
|
|
791
|
+
│ │ └── app.pln
|
|
792
|
+
│ ├── id-verification/ — acceptance example (uploads + OCR matching)
|
|
793
|
+
│ │ ├── app.pln
|
|
794
|
+
│ │ └── make-sample-id.js
|
|
795
|
+
│ └── whatsapp-bot/ — WhatsApp bots (QR and pairing linking)
|
|
796
|
+
│ ├── qr.pln
|
|
797
|
+
│ └── pairing.pln
|
|
798
|
+
│
|
|
799
|
+
├── tests/
|
|
800
|
+
│ ├── compiler.test.js — language, CLI and formatter coverage
|
|
801
|
+
│ ├── build.test.js — build model, config and packaging coverage
|
|
802
|
+
│ ├── backend.test.js — web/database/email/cache runtime tests
|
|
803
|
+
│ ├── telegram.test.js — Telegram bot runtime tests
|
|
804
|
+
│ ├── ocr.test.js — OCR statement tests
|
|
805
|
+
│ ├── runtime.test.js — uploads, database and bot feature suite
|
|
806
|
+
│ ├── whatsapp.test.js — WhatsApp bot runtime tests
|
|
807
|
+
│ └── acceptance.test.js — boots the example projects over live HTTP
|
|
808
|
+
│
|
|
809
|
+
├── docs/
|
|
810
|
+
│ ├── PlainScript_SPEC.md
|
|
811
|
+
│ └── index.html
|
|
812
|
+
│
|
|
813
|
+
├── package.json
|
|
814
|
+
└── README.md
|
|
815
|
+
```
|