plainscript-lang 1.0.2 → 1.0.3

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 (74) hide show
  1. package/README.md +173 -738
  2. package/compiler/bundler.js +83 -12
  3. package/compiler/cli.js +74 -27
  4. package/compiler/dependency-detector.js +11 -0
  5. package/compiler/generator.js +372 -35
  6. package/compiler/lexer.js +2 -0
  7. package/compiler/parser.js +410 -28
  8. package/compiler/sourcemap.js +142 -0
  9. package/compiler/version.js +1 -1
  10. package/docs/CAPABILITY_GAP_AUDIT.md +98 -534
  11. package/docs/PLAINSCRIPT-SPEC.md +304 -551
  12. package/docs/index.html +127 -598
  13. package/docs/website/script.js +185 -1006
  14. package/docs/website/style.css +220 -656
  15. package/examples/ai-providers.pln +7 -0
  16. package/examples/arrays.pln +4 -12
  17. package/examples/async-errors.pln +18 -0
  18. package/examples/auth-api.pln +3 -50
  19. package/examples/auth-sessions.pln +32 -0
  20. package/examples/basics.pln +14 -0
  21. package/examples/bots.pln +13 -0
  22. package/examples/cache-and-jobs.pln +6 -28
  23. package/examples/cache-schedule.pln +22 -0
  24. package/examples/collections.pln +15 -0
  25. package/examples/concurrency.pln +12 -43
  26. package/examples/conditions.pln +22 -0
  27. package/examples/database.pln +6 -39
  28. package/examples/day2.pln +6 -6
  29. package/examples/day3.pln +4 -10
  30. package/examples/deployment.pln +3 -9
  31. package/examples/email-send.pln +3 -22
  32. package/examples/error-handling.pln +6 -54
  33. package/examples/expressions.pln +7 -40
  34. package/examples/file-uploads.pln +5 -34
  35. package/examples/files-and-config.pln +5 -46
  36. package/examples/files.pln +12 -0
  37. package/examples/football-backend/app.pln +21 -20
  38. package/examples/functions.pln +17 -0
  39. package/examples/hello.pln +2 -3
  40. package/examples/http-client.pln +3 -44
  41. package/examples/http.pln +11 -0
  42. package/examples/id-verification/app.pln +4 -3
  43. package/examples/id-verification/make-sample-id.js +29 -42
  44. package/examples/json.pln +11 -0
  45. package/examples/loops.pln +13 -11
  46. package/examples/modules/app.pln +3 -16
  47. package/examples/modules/main.pln +4 -0
  48. package/examples/modules/math.pln +5 -16
  49. package/examples/mongo.pln +33 -0
  50. package/examples/objects.pln +3 -11
  51. package/examples/ocr.pln +22 -0
  52. package/examples/packages.pln +6 -0
  53. package/examples/record-kinds.pln +6 -42
  54. package/examples/records.pln +15 -0
  55. package/examples/rest-api-fetch.pln +6 -90
  56. package/examples/rest-api.pln +5 -65
  57. package/examples/scheduled-tasks.pln +4 -23
  58. package/examples/search-and-filter.pln +4 -34
  59. package/examples/server.pln +5 -24
  60. package/examples/sessions-and-cookies.pln +4 -50
  61. package/examples/sqlite.pln +23 -0
  62. package/examples/start.pln +2 -2
  63. package/examples/stdlib.pln +4 -41
  64. package/examples/string-verbs.pln +16 -0
  65. package/examples/telegram-ai-bot.pln +19 -0
  66. package/examples/telegram-bot.pln +4 -40
  67. package/examples/testing.pln +13 -0
  68. package/examples/web-api.pln +27 -0
  69. package/examples/web-app.pln +4 -16
  70. package/examples/websocket-server.pln +5 -26
  71. package/examples/websocket.pln +13 -0
  72. package/examples/whatsapp-bot/pairing.pln +4 -5
  73. package/examples/whatsapp-bot/qr.pln +7 -3
  74. package/package.json +3 -2
@@ -1,584 +1,337 @@
1
- # PlainScript Language Specification (v2.4)
1
+ # PlainScript 1.0.3 language specification
2
2
 
3
- Version: 2.4
4
- Status: Stable
5
- File Extension: .pln
3
+ This reference covers the syntax implemented by `compiler/lexer.js` and
4
+ `compiler/parser.js`. The runtime it generates lives in
5
+ `compiler/generator.js`. Every example here is checked against the
6
+ repository's maintained example set.
6
7
 
7
- Tagline: "When even a simple sentence can be code."
8
+ ## Design
8
9
 
9
- ---
10
+ PlainScript is a line-oriented, intent-oriented language made for Node.js.
11
+ Source files use `.pln`. Blocks end with `done` unless the syntax says
12
+ `together`. Whitespace does not matter.
10
13
 
11
- ## Mission
14
+ The basic declaration forms are:
12
15
 
13
- PlainScript is an Intent-Oriented Programming Language (IOPL).
16
+ ```plainscript
17
+ remember name as "Ada"
18
+ let age be 36
19
+ name becomes "Grace"
20
+ show name
21
+ ```
14
22
 
15
- Its goal is to let developers describe WHAT they want while the compiler decides HOW JavaScript should implement it.
23
+ Comments begin with `//`. Double-quoted strings support escapes. Backtick
24
+ strings keep their content as-is and support `${expression}` interpolation.
16
25
 
17
- PlainScript is designed to be: beginner-friendly, readable, predictable, consistent, and easy to teach.
26
+ ## Values and expressions
18
27
 
19
- Every keyword should be understandable by a 12-year-old.
28
+ PlainScript has strings, template strings, numbers, booleans, `null`,
29
+ `undefined`, BigInt, arrays, objects, identifiers, function calls, member
30
+ access, optional member access, and indexed access.
20
31
 
21
- ---
32
+ ```plainscript
33
+ remember names as ["Ada", "Grace"]
34
+ remember user as {name: "Ada", active: true}
35
+ show names[0]
36
+ show user?.name
37
+ ```
22
38
 
23
- ## Core Principles
39
+ English-style collection expressions:
24
40
 
25
- 1. One way to do everything.
26
- 2. Readability over fewer characters.
27
- 3. Keywords never have aliases.
28
- 4. Error messages should teach.
29
- 5. JavaScript is an implementation detail.
30
- 6. Code should read like documentation.
41
+ ```plainscript
42
+ remember items as list with "one", "two", "three"
43
+ remember profile as record with name "Ada" and role "admin" done
44
+ show first item from items
45
+ show last item from items
46
+ show item one from items
47
+ show items at position 1
48
+ ```
31
49
 
32
- ---
33
-
34
- ## Comments
35
-
36
- // This is a comment
37
-
38
- ---
39
-
40
- ## Variables
41
-
42
- Declare:
43
-
44
- let name be "Ayokunle"
45
- let age be 16
46
- remember age as 16
47
-
48
- Reassign:
49
-
50
- set age to 17
51
- set age to 20
52
- set age to 21
53
-
54
- All three forms are valid; `let x be V` is the preferred form.
55
-
56
- ---
57
-
58
- ## Printing
59
-
60
- show "Hello"
61
- show("Hello")
62
- show age
63
- show(players[0])
64
- show user.name
65
-
66
- Both keyword form (`show expr`) and call form (`show(expr)`) are valid and produce identical output.
67
-
68
- ---
50
+ Arithmetic uses `+`, `-`, `*`, `/`, `%`, and `**`, with normal
51
+ precedence. Word forms `plus`, `minus`, `times`, and `divided by` also work.
52
+ `??` plus unary `-`, `wait for`, `typeof`, `void`, and `delete` are
53
+ supported.
69
54
 
70
55
  ## Conditions
71
56
 
72
- when age is 18
73
- show "Adult"
74
- otherwise
75
- show "Minor"
76
- done
77
-
78
- when age is 18
79
- show "Adult"
80
- else
81
- show "Minor"
82
- done
83
-
84
- ### Comparison Operators
85
-
86
- | PlainScript | JavaScript |
87
- |------------------------------|--------------------|
88
- | `is` / `is equal to` | `===` |
89
- | `is not` | `!==` |
90
- | `is greater than` | `>` |
91
- | `is above` | `>` |
92
- | `is less than` | `<` |
93
- | `is below` | `<` |
94
- | `is at least` | `>=` |
95
- | `is at most` | `<=` |
96
- | `is empty` | `.length === 0` |
97
- | `is not empty` | `.length > 0` |
98
- | `contains "x"` | `.includes("x")` |
99
- | `starts with "x"` | `.startsWith("x")` |
100
- | `ends with "x"` | `.endsWith("x")` |
101
- | `between A and B` | `>= A && <= B` |
102
- | `a more than b` | `>` |
103
- | `a fewer than b` | `<` |
104
- | `a same as b` | `===` |
105
- | `a different from b` | `!==` |
106
- | `name starts as "x"` | `.startsWith("x")` |
107
- | `name ends as "x"` | `.endsWith("x")` |
108
- | `name made of "x"` | `.includes("x")` |
109
-
110
- ---
111
-
112
- ## v2.4 Near-English Syntax
113
-
114
- PlainScript v2.4 introduces near-English syntax forms that make code read like natural sentences. These forms are fully interchangeable with their existing equivalents.
115
-
116
- ### Array Position Access
117
-
118
- let first be name at position 1 in list
119
-
120
- Equivalent to `list[0]` (0-indexed). The phrase `at position N` provides readable array indexing.
121
-
122
- ### Property Existence Check
123
-
124
- when obj has field "name"
125
- show "exists"
126
- done
127
-
128
- Equivalent to `"name" in obj`. The phrase `has field` reads naturally for property checks.
129
-
130
- ### String Matching
131
-
132
- when name starts as "Ay"
133
- show "starts with prefix"
134
- done
135
-
136
- when name ends as "le"
137
- show "ends with suffix"
138
- done
139
-
140
- when name made of "oku"
141
- show "contains substring"
142
- done
143
-
144
- These are English alternatives to `starts with`, `ends with`, and `contains`.
145
-
146
- ### Comparison Operators
147
-
148
- when a more than b
149
- show "a is greater"
150
- done
151
-
152
- when a fewer than b
153
- show "a is smaller"
154
- done
155
-
156
- when a same as b
157
- show "equal"
158
- done
159
-
160
- when a different from b
161
- show "not equal"
162
- done
163
-
164
- These replace `is greater than`, `is less than`, `is equal to`, and `is not`.
165
-
166
- ### Function Calls with `together`
167
-
168
- greet together
169
- add together 5, 7
170
- fill result with add together 5, 7
171
-
172
- The `together` keyword marks a function call. The `fill ... with` form captures the return value.
173
-
174
- ### Throwing Errors
175
-
176
- raise "something went wrong"
177
-
178
- Equivalent to `throw new Error("something went wrong")`.
179
-
180
- ### Recover Alternatives
181
-
182
- try
183
- riskyOperation()
184
- handled by
185
- show "fallback"
186
- done
187
-
188
- The `handled by` clause is an alternative to `recover as` for simpler error recovery where the error value is not needed.
189
-
190
- ### Ternary Expressions
191
-
192
- let label be choosing age is more than 18 then "adult" otherwise "minor"
193
-
194
- Equivalent to `age > 18 ? "adult" : "minor"`. Reads as a natural English decision.
195
-
196
- ---
57
+ ```plainscript
58
+ if age is at least 18 and name contains "A"
59
+ show "adult"
60
+ otherwise
61
+ show "minor"
62
+ done
63
+ ```
64
+
65
+ Operators:
66
+
67
+ | Syntax | Result |
68
+ | --- | --- |
69
+ | `is`, `same as` | `===` |
70
+ | `is not`, `different from` | `!==` |
71
+ | `more than`, `is greater than`, `is above` | `>` |
72
+ | `fewer than`, `is less than`, `is below` | `<` |
73
+ | `is at least` | `>=` |
74
+ | `is most` | `<=` |
75
+ | `contains`, `starts with`, `ends with`, `made of` | string predicates |
76
+ | `between low and high` | inclusive range |
77
+ | `has field field` | property existence |
78
+ | `instanceof Kind` | instance test |
79
+
80
+ Use `and`, `or`, and `not` to combine conditions. Inline conditionals use
81
+ `choosing condition then yesValue otherwise noValue`.
197
82
 
198
83
  ## Functions
199
84
 
200
- to greet
201
- show "Hello"
202
- done
85
+ Write a function with `make` and return a value with `give`:
203
86
 
204
- to add a and b together
205
- give back a + b
206
- done
207
-
208
- to multiply x and y together
209
- give back x * y
210
- done
87
+ ```plainscript
88
+ make add(a, b)
89
+ give a + b
90
+ done
211
91
 
212
- greet()
213
- show add(5, 7)
92
+ show add(2, 3)
93
+ ```
214
94
 
215
- ---
95
+ Function parameters can have simple defaults:
216
96
 
217
- ## Loops
97
+ ```plainscript
98
+ make greet(name as "friend")
99
+ give `Hello, ${name}`
100
+ done
101
+ ```
218
102
 
219
- For each:
103
+ Aliases like `define`, `function`, `return`, and `give back` also work. Use
104
+ `make` and `give` for the readable form:
220
105
 
221
- for each player in players
222
- show player
223
- done
106
+ ```plainscript
107
+ make add(a, b)
108
+ give a + b
109
+ done
110
+ ```
111
+
112
+ `yield` turns a function into a generator. Functions can use `wait for` and
113
+ other async operations.
224
114
 
225
- For every (alias for for each):
115
+ ## Control flow
226
116
 
227
- for every item in basket
228
- show item
229
- done
117
+ ```plainscript
118
+ for each item in items
119
+ show item
120
+ done
230
121
 
231
- For index:
122
+ for index i from 0 to 2
123
+ show i
124
+ done
232
125
 
233
- for index i from 0 to 9
234
- show i
235
- done
126
+ while count is less than 3
127
+ count becomes count + 1
128
+ done
129
+ ```
236
130
 
237
- for index i from 10 to 1
238
- show i
239
- done
131
+ Use `break` and `continue` inside loops. `match value against` uses `->`
132
+ case arrows and `otherwise`. `switch value against` works the same way and
133
+ is just another way to write it.
240
134
 
241
- While:
135
+ ## Record kinds
136
+
137
+ ```plainscript
138
+ define a kind called "Player" with
139
+ name is ""
140
+ goals is 0
141
+ done
242
142
 
243
- while age is less than 18
244
- set age to age + 1
245
- done
143
+ remember player as create a Player with name "Ada" and goals 4
144
+ ```
246
145
 
247
- ---
248
-
249
- ## Collections
250
-
251
- Arrays:
252
-
253
- let players be list with "Haaland", "Foden", "Rodri"
254
- let first be players[0]
255
- set players[1] to "Palmer"
256
-
257
- Destructuring:
258
-
259
- let nums be list with 1, 2, 3
260
- let [a, b, c] be nums
261
- let obj be record with x 10 and y 20
262
- let {x, y} be obj
263
-
264
- Objects:
265
-
266
- let user be record with
267
- name "Ayokunle"
268
- age 17
269
- done
270
-
271
- show name of user
272
- set user.age to 18
273
-
274
- Spread:
275
-
276
- let more be [...nums, 4]
277
-
278
- ---
279
-
280
- ## Record Kinds (Classes)
281
-
282
- to define a kind called "Person" with
283
- name is ""
284
- age is 0
285
- done
286
-
287
- let ada be create a Person with name "Ada" and age 17
288
- show name of ada
289
- show ada.age
290
-
291
- ---
292
-
293
- ## Logical Assignment
294
-
295
- let flag be false
296
- flag or is true
297
- show flag
298
-
299
- let val be null
300
- val nullish is "default"
301
- show val
302
-
303
- ---
304
-
305
- ## Web Servers
306
-
307
- web app
308
- allow cors
309
-
310
- group "/api"
311
- route get "/teams"
312
- let rows be query
313
- select id, name from teams order by name
314
- done
315
- show rows
316
- done
317
-
318
- route post "/players"
319
- let missing be validate(body of request, list with "name", "email")
320
- when length of missing is greater than 0
321
- status 400
322
- show missing
323
- otherwise
324
- show "created"
325
- done
326
- done
327
- done
328
-
329
- start 3000
330
- done
331
-
332
- Classic Express style also works:
333
-
334
- use express
335
- let app be express()
336
- serve folder "public"
337
-
338
- when someone visits "/"
339
- show "Hello!"
340
- done
341
-
342
- listen on 3000
343
- show "running"
344
- done
345
-
346
- ---
347
-
348
- ## Databases
349
-
350
- database "app.db"
351
-
352
- execute
353
- CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)
354
- done
355
-
356
- insert
357
- INSERT INTO users (name) VALUES ('Alice')
358
- done
359
-
360
- query
361
- SELECT * FROM users
362
- done
363
-
364
- Placeholders:
365
-
366
- database "app.db"
367
- let who be "ana"
368
- insert
369
- INSERT INTO users (name) VALUES ({who})
370
- done
371
-
372
- let adults be query
373
- SELECT * FROM users WHERE age >= {minAge}
374
- done
375
-
376
- Transactions:
377
-
378
- database "app.db"
379
- transaction
380
- insert
381
- INSERT INTO users (name) VALUES ('bob')
382
- done
383
- done
384
-
385
- PostgreSQL:
386
-
387
- postgres env("DATABASE_URL")
388
-
389
- ---
390
-
391
- ## HTTP Client
392
-
393
- let r be get "https://api.example.com/users"
394
- when ok of r is true
395
- show status of r
396
- show data of r
397
- done
398
-
399
- let body be record with name "Ada"
400
- let created be post "https://api.example.com/users" with body
401
- headers { accept: "application/json" }
402
- timeout 5000
403
- done
404
-
405
- delete "https://api.example.com/users/9"
406
-
407
- ---
408
-
409
- ## Error Handling
410
-
411
- try
412
- let data be jsonDecode(raw)
413
- recover as err
414
- show "bad json: " + message of err
415
- done
416
-
417
- retry 3 times every 5 seconds
418
- wait for fetch("https://flaky.api")
419
- done
420
-
421
- ---
422
-
423
- ## Testing
424
-
425
- test "addition"
426
- check add(2, 3) equals 5
427
- check "hello" contains "ell"
428
- check jsonDecode("not json") raises "JSON"
429
- done
146
+ `define a kind called` makes a new record kind. Fields use default
147
+ expressions. `create a Kind with field value and field value` builds an
148
+ instance.
430
149
 
431
- ---
432
-
433
- ## Exports
434
-
435
- let configVersion be 3
436
- export configVersion
437
-
438
- ---
439
-
440
- ## Standard Library
441
-
442
- All built-in functions are available without any `use` or `import` statement.
443
-
444
- ### Strings & Numbers
445
-
446
- | PlainScript | JavaScript equivalent |
447
- |-----------------|-------------------------|
448
- | `length(x)` | `(x).length` |
449
- | `uppercase(x)` | `(x).toUpperCase()` |
450
- | `lowercase(x)` | `(x).toLowerCase()` |
451
- | `random()` | `Math.random()` |
452
- | `round(x)` | `Math.round(x)` |
453
-
454
- ### Time & System
455
-
456
- | PlainScript | JavaScript equivalent |
457
- |----------------|----------------------------------------|
458
- | `time()` | `Date.now()` |
459
- | `date()` | `new Date().toISOString()` |
460
- | `sleep(ms)` | `Atomics.wait(...)` (synchronous) |
461
- | `uuid()` | `require('crypto').randomUUID()` |
462
- | `env(key)` | `process.env[key]` |
463
- | `exit(code)` | `process.exit(code)` |
464
-
465
- ### JSON
466
-
467
- | PlainScript | JavaScript equivalent |
468
- |--------------------|-----------------------------|
469
- | `jsonEncode(x)` | `JSON.stringify(x)` |
470
- | `jsonDecode(s)` | `JSON.parse(s)` |
471
-
472
- ---
473
-
474
- ## Imports
475
-
476
- import "./math.pln"
477
- import { helper } from "./util.pln"
478
-
479
- ---
480
-
481
- ## Packages
482
-
483
- use axios
484
- use node-fetch as fetch
485
- use left-pad@^1.3.0
486
- use @scope/package-name
487
-
488
- ---
489
-
490
- ## Reserved Keywords
491
-
492
- let print
493
- define function give return
494
- if otherwise else end
495
- for each every in
496
- while
497
- use import include load
498
- when someone visits
499
- listen start_on serve_on
500
- reply respond send_back
501
- serve serve_static serve_public
502
- folder
503
- is above below at least most
504
- not empty contains
505
- starts ends with between and or
506
- web route start run_on
507
- database connect_database use_database
508
- query insert update delete execute
509
- ask prompt
510
- ocr
511
- true false null
512
- try recover retry
513
- wait
514
- accept limit allow
515
- require api key
516
- enable sessions
517
- destroy session
518
- cookie expires
519
- limit requests
520
- google oauth
521
- define kind
522
- test check export
523
- debugger
524
- symbol
525
- at position has field
526
- starts as ends as made of
527
- more than fewer than same as different from
528
- together fill with
529
- raise handled by
530
- choosing then
531
-
532
- ---
533
-
534
- ## Built-in Functions (stdlib)
535
-
536
- ### Concurrency
537
- - `all of [...]` - Promise.all
538
- - `any of [...]` - Promise.race
539
- - `settled of [...]` - Promise.allSettled
540
- - `wait for <expr>` - await
541
- - `retry N times every M seconds` - retry with backoff
542
-
543
- ### Collections
544
- - `length(x)` - array/string length
545
- - `first/last` - array access
546
- - `spread of x` - [...x]
547
- - `unique(x)` - deduplicate
548
- - `sort/reverse` - ordering
549
-
550
- ### Files
551
- - `read(path)` / `write(data, path)`
552
- - `fileExists(path)`
553
-
554
- ### Crypto
555
- - `sha256(text)` / `base64Encode` / `base64Decode`
556
-
557
- ### Network
558
- - `get/post/put/patch/delete "<url>"` - HTTP requests
559
-
560
- ### Database
561
- - `database "file"` / `query` / `insert` / `update` / `delete` / `execute`
562
-
563
- ### Web
564
- - `web app` / `route` / `start` / `serve folder`
565
-
566
- ---
567
-
568
- ## CLI Commands
569
-
570
- | Command | Description |
571
- |---------|-------------|
572
- | `plainscript new <name>` | Scaffold a new project |
573
- | `plainscript build [file]` | Compile to dist/ |
574
- | `plainscript run <file.pln>` | Install deps, compile, run |
575
- | `plainscript check <file.pln>` | Syntax check only |
576
- | `plainscript fmt <file.pln>` | Format in-place |
577
- | `plainscript install` | Install detected dependencies |
578
- | `plainscript start` | Build and run |
579
- | `plainscript doctor` | Environment health check |
580
-
581
- ---
582
-
583
- This document is the single source of truth for PlainScript v2.4.
584
- Every compiler implementation must follow this specification.
150
+ ## Modules and packages
151
+
152
+ ```plainscript
153
+ import "./math.pln"
154
+ import { circleArea } from "./geometry.pln"
155
+ export circleArea
156
+ use express
157
+ ```
158
+
159
+ Imports get bundled in dependency order. `use` declares an npm package.
160
+
161
+ ## Web server syntax
162
+
163
+ ```plainscript
164
+ web app
165
+ allow cors
166
+
167
+ route get "/health"
168
+ reply json
169
+ ok is true
170
+ done
171
+ done
172
+
173
+ when nothing matches
174
+ status 404
175
+ reply "not found"
176
+ done
177
+
178
+ start 3000
179
+ ```
180
+
181
+ Methods are `get`, `post`, `put`, `patch`, and `delete`. Request values use
182
+ `body of request`, `param("id")`, `query("name")`, `header("x-token")`,
183
+ `upload("file")`, and `uploads("file")`.
184
+
185
+ The server also supports:
186
+
187
+ ```plainscript
188
+ enable sessions "secret"
189
+ route get "/preferences"
190
+ set cookie "theme" to "dark" expires in 7 days
191
+ reply "saved"
192
+ done
193
+ limit requests to 100 per minute
194
+ require api key from env("API_KEY")
195
+ accept uploads limit "5 MB" allow list with "image/png" folder "uploads"
196
+ ```
197
+
198
+ ## Database and HTTP
199
+
200
+ ```plainscript
201
+ database "app.db" using "wasm"
202
+ execute
203
+ CREATE TABLE users (name TEXT)
204
+ done
205
+ insert
206
+ INSERT INTO users (name) VALUES ("Ada")
207
+ done
208
+ remember users as query
209
+ SELECT name FROM users
210
+ done
211
+ ```
212
+
213
+ SQL blocks are closed by `done`. `{variable}` placeholders are bound safely.
214
+ `transaction ... done` groups writes. `postgres connection` generates
215
+ PostgreSQL code instead.
216
+
217
+ HTTP client expressions:
218
+
219
+ ```plainscript
220
+ remember response as get "https://example.com" timeout 5000
221
+ remember created as post "https://example.com" with {name: "Ada"} headers {accept: "application/json"}
222
+ ```
223
+
224
+ ## Errors and async
225
+
226
+ ```plainscript
227
+ try
228
+ remember value as get "https://example.com" timeout 5000
229
+ recover as error
230
+ show message of error
231
+ finally
232
+ show "finished"
233
+
234
+ retry 3 times every 1 second
235
+ show "retry"
236
+ done
237
+ ```
238
+
239
+ Concurrency helpers are `allOf`, `anyOf`, `settledOf`, and `withTimeout`.
240
+ Recurring blocks use `every 5 minutes ... done` and
241
+ `schedule "0 * * * *" ... done`.
242
+
243
+ ## AI providers
244
+
245
+ `chat(model, messages, options)` and `embedText(model, text, options)` talk
246
+ to an OpenAI-compatible API. Provider presets pick safe defaults for the
247
+ endpoint and the environment variable:
248
+
249
+ | Provider | API key | Default base |
250
+ | --- | --- | --- |
251
+ | `openai` | `OPENAI_API_KEY` | `https://api.openai.com/v1` |
252
+ | `groq` | `GROQ_API_KEY` | `https://api.groq.com/openai/v1` |
253
+ | `openrouter` | `OPENROUTER_API_KEY` | `https://openrouter.ai/api/v1` |
254
+ | `together` | `TOGETHER_API_KEY` | `https://api.together.xyz/v1` |
255
+ | `fireworks` | `FIREWORKS_API_KEY` | `https://api.fireworks.ai/inference/v1` |
256
+ | `deepseek` | `DEEPSEEK_API_KEY` | `https://api.deepseek.com/v1` |
257
+
258
+ ```plainscript
259
+ remember answer as chat("llama-3.3-70b-versatile", "Hello from PlainScript", {
260
+ provider: "groq",
261
+ key: env("GROQ_API_KEY"),
262
+ temperature: 0.2,
263
+ maxTokens: 200
264
+ })
265
+ remember explicit as chatWith("groq", "llama-3.3-70b-versatile", "Hello")
266
+ show answer
267
+ ```
268
+
269
+ `base`, `key`, `headers`, `temperature`, `maxTokens`, and `responseFormat`
270
+ are optional. Custom providers can supply a provider name plus `base` and
271
+ `key`; the runtime falls back to `PROVIDER_API_KEY` and `PROVIDER_BASE_URL`.
272
+ These calls work in ordinary programs, routes, jobs, and messaging handlers.
273
+
274
+ ## WebSockets, cache, bots, and OCR
275
+
276
+ ```plainscript
277
+ websocket server on 8080
278
+ when socket connects
279
+ send socket "connected"
280
+ done
281
+ when socket sends message
282
+ broadcast message
283
+ done
284
+ done
285
+
286
+ cache env("REDIS_URL")
287
+ cacheSet("key", "value", 60)
288
+ remember value as cacheGet("key")
289
+ ```
290
+
291
+ Telegram:
292
+
293
+ ```plainscript
294
+ bot env("TELEGRAM_BOT_TOKEN")
295
+ when someone sends "/start"
296
+ reply "Welcome"
297
+ done
298
+ start telegram bot
299
+ ```
300
+
301
+ Inside a Telegram handler, `message`, `text`, `args`, `matches`, `chat`,
302
+ `chatId`, and callback `data` hold the update context. Fixed replies use
303
+ `reply "text"`; provider-backed replies can use `chatWith` before `reply`.
304
+ `telegramCall(method, params)` calls any Telegram Bot API method.
305
+
306
+ WhatsApp uses `whatsapp bot ... done`, with `auth`, `login qr`, `login
307
+ pairing`, and `on message` clauses. OCR uses:
308
+
309
+ ```plainscript
310
+ ocr path of file as text
311
+ ```
312
+
313
+ ## Native tests
314
+
315
+ ```plainscript
316
+ test "addition"
317
+ check add(2, 3) equals 5
318
+ done
319
+ ```
320
+
321
+ Assertions are `equals`, `is`, `contains`, and `raises`.
322
+
323
+ ## CLI
324
+
325
+ ```text
326
+ plainscript check [target]
327
+ plainscript build [file.pln]
328
+ plainscript run <file.pln>
329
+ plainscript start
330
+ plainscript fmt <file.pln>
331
+ plainscript install
332
+ plainscript doctor
333
+ plainscript version
334
+ ```
335
+
336
+ `check` parses imports, generates JavaScript, and validates that output with
337
+ Node's parser without writing files.