plainscript-lang 1.0.2-rfc → 1.0.3-beta

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 (67) hide show
  1. package/README.md +194 -736
  2. package/compiler/cli.js +13 -17
  3. package/compiler/generator.js +93 -21
  4. package/compiler/version.js +1 -1
  5. package/docs/CAPABILITY_GAP_AUDIT.md +98 -536
  6. package/docs/PLAINSCRIPT-SPEC.md +308 -557
  7. package/docs/index.html +101 -599
  8. package/docs/website/script.js +59 -1029
  9. package/docs/website/style.css +74 -656
  10. package/examples/ai-providers.pln +7 -0
  11. package/examples/arrays.pln +4 -12
  12. package/examples/async-errors.pln +18 -0
  13. package/examples/auth-api.pln +3 -50
  14. package/examples/auth-sessions.pln +32 -0
  15. package/examples/basics.pln +14 -0
  16. package/examples/bots.pln +13 -0
  17. package/examples/cache-and-jobs.pln +6 -28
  18. package/examples/cache-schedule.pln +22 -0
  19. package/examples/collections.pln +15 -0
  20. package/examples/concurrency.pln +12 -43
  21. package/examples/conditions.pln +22 -0
  22. package/examples/database.pln +6 -39
  23. package/examples/day2.pln +6 -6
  24. package/examples/day3.pln +4 -10
  25. package/examples/deployment.pln +3 -9
  26. package/examples/email-send.pln +3 -22
  27. package/examples/error-handling.pln +6 -54
  28. package/examples/expressions.pln +7 -40
  29. package/examples/file-uploads.pln +5 -34
  30. package/examples/files-and-config.pln +5 -46
  31. package/examples/files.pln +12 -0
  32. package/examples/football-backend/app.pln +21 -20
  33. package/examples/functions.pln +17 -0
  34. package/examples/hello.pln +2 -3
  35. package/examples/http-client.pln +3 -44
  36. package/examples/http.pln +11 -0
  37. package/examples/id-verification/app.pln +4 -3
  38. package/examples/id-verification/make-sample-id.js +29 -42
  39. package/examples/json.pln +11 -0
  40. package/examples/loops.pln +13 -11
  41. package/examples/modules/app.pln +3 -16
  42. package/examples/modules/main.pln +4 -0
  43. package/examples/modules/math.pln +5 -16
  44. package/examples/objects.pln +3 -11
  45. package/examples/ocr.pln +22 -0
  46. package/examples/packages.pln +6 -0
  47. package/examples/record-kinds.pln +6 -42
  48. package/examples/records.pln +15 -0
  49. package/examples/rest-api-fetch.pln +6 -90
  50. package/examples/rest-api.pln +5 -65
  51. package/examples/scheduled-tasks.pln +4 -23
  52. package/examples/search-and-filter.pln +4 -34
  53. package/examples/server.pln +5 -24
  54. package/examples/sessions-and-cookies.pln +4 -50
  55. package/examples/sqlite.pln +23 -0
  56. package/examples/start.pln +2 -2
  57. package/examples/stdlib.pln +4 -41
  58. package/examples/telegram-ai-bot.pln +19 -0
  59. package/examples/telegram-bot.pln +4 -40
  60. package/examples/testing.pln +13 -0
  61. package/examples/web-api.pln +27 -0
  62. package/examples/web-app.pln +4 -16
  63. package/examples/websocket-server.pln +5 -26
  64. package/examples/websocket.pln +13 -0
  65. package/examples/whatsapp-bot/pairing.pln +4 -5
  66. package/examples/whatsapp-bot/qr.pln +7 -3
  67. package/package.json +2 -2
@@ -1,584 +1,335 @@
1
- # PlainScript Language Specification (v2.4)
1
+ # PlainScript 1.0.3-beta language specification
2
2
 
3
- Version: 2.4
4
- Status: Stable
5
- File Extension: .pln
3
+ This reference describes the syntax implemented by `compiler/lexer.js` and
4
+ `compiler/parser.js`. The generated runtime is implemented in
5
+ `compiler/generator.js`. Examples in this document are checked from 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 for Node.js. Source
11
+ files use `.pln`. Blocks close with `done` unless the syntax explicitly uses
12
+ `together`. Whitespace is not semantic.
10
13
 
11
- ## Mission
14
+ The canonical 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 preserve content 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
+ Values include strings, template strings, numbers, booleans, `null`,
29
+ `undefined`, BigInt, arrays, objects, identifiers, calls, member access,
30
+ 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 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 supports `+`, `-`, `*`, `/`, `%`, and `**`, with normal
51
+ precedence. Word forms `plus`, `minus`, `times`, and `divided by` are also
52
+ recognized. `??` and unary `-`, `wait for`, `typeof`, `void`, and `delete`
53
+ are implemented.
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
203
-
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
85
+ ```plainscript
86
+ make add(a, b)
87
+ give a + b
88
+ done
211
89
 
212
- greet()
213
- show add(5, 7)
90
+ show add(2, 3)
91
+ ```
214
92
 
215
- ---
93
+ Function parameters can have simple defaults:
216
94
 
217
- ## Loops
95
+ ```plainscript
96
+ make greet(name as "friend")
97
+ give `Hello, ${name}`
98
+ done
99
+ ```
218
100
 
219
- For each:
101
+ Aliases `define`, `function`, `return`, and `give back` are implemented. The
102
+ readable declaration form is:
220
103
 
221
- for each player in players
222
- show player
223
- done
104
+ ```plainscript
105
+ make add(a, b)
106
+ give a + b
107
+ done
108
+ ```
224
109
 
225
- For every (alias for for each):
226
-
227
- for every item in basket
228
- show item
229
- done
110
+ `yield` creates a generator function. Functions may use `wait for` and other
111
+ async operations.
112
+
113
+ ## Control flow
230
114
 
231
- For index:
232
-
233
- for index i from 0 to 9
234
- show i
235
- done
236
-
237
- for index i from 10 to 1
238
- show i
239
- done
115
+ ```plainscript
116
+ for each item in items
117
+ show item
118
+ done
119
+
120
+ for index i from 0 to 2
121
+ show i
122
+ done
240
123
 
241
- While:
242
-
243
- while age is less than 18
244
- set age to age + 1
245
- done
246
-
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
124
+ while count is less than 3
125
+ count becomes count + 1
126
+ done
127
+ ```
128
+
129
+ Use `break` and `continue` inside loops. `match value against` uses `->`
130
+ case arrows and `otherwise`. `switch value against` is an equivalent
131
+ discriminant form.
132
+
133
+ ## Record kinds
134
+
135
+ ```plainscript
136
+ define a kind called "Player" with
137
+ name is ""
138
+ goals is 0
139
+ done
140
+
141
+ remember player as create a Player with name "Ada" and goals 4
142
+ ```
143
+
144
+ `define a kind called` creates a record kind. Fields use default expressions.
145
+ `create a Kind with field value and field value` constructs an instance.
430
146
 
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.
147
+ ## Modules and packages
148
+
149
+ ```plainscript
150
+ import "./math.pln"
151
+ import { circleArea } from "./geometry.pln"
152
+ export circleArea
153
+ use express
154
+ ```
155
+
156
+ Imports are bundled in dependency order. `use` declares an npm package.
157
+
158
+ ## Web server syntax
159
+
160
+ ```plainscript
161
+ web app
162
+ allow cors
163
+
164
+ route get "/health"
165
+ reply json
166
+ ok is true
167
+ done
168
+ done
169
+
170
+ when nothing matches
171
+ status 404
172
+ reply "not found"
173
+ done
174
+
175
+ start 3000
176
+ ```
177
+
178
+ Methods are `get`, `post`, `put`, `patch`, and `delete`. Request values use
179
+ `body of request`, `param("id")`, `query("name")`, `header("x-token")`,
180
+ `upload("file")`, and `uploads("file")`.
181
+
182
+ Server capabilities include:
183
+
184
+ ```plainscript
185
+ enable sessions "secret"
186
+ route get "/preferences"
187
+ set cookie "theme" to "dark" expires in 7 days
188
+ reply "saved"
189
+ done
190
+ limit requests to 100 per minute
191
+ require api key from env("API_KEY")
192
+ accept uploads limit "5 MB" allow list with "image/png" folder "uploads"
193
+ ```
194
+
195
+ ## Database and HTTP
196
+
197
+ ```plainscript
198
+ database "app.db" using "wasm"
199
+ execute
200
+ CREATE TABLE users (name TEXT)
201
+ done
202
+ insert
203
+ INSERT INTO users (name) VALUES ("Ada")
204
+ done
205
+ remember users as query
206
+ SELECT name FROM users
207
+ done
208
+ ```
209
+
210
+ SQL blocks are closed by `done`. `{variable}` placeholders are bound safely.
211
+ `transaction ... done` groups writes. `postgres connection` selects
212
+ PostgreSQL generation.
213
+
214
+ HTTP client expressions:
215
+
216
+ ```plainscript
217
+ remember response as get "https://example.com" timeout 5000
218
+ remember created as post "https://example.com" with {name: "Ada"} headers {accept: "application/json"}
219
+ ```
220
+
221
+ ## Errors and async
222
+
223
+ ```plainscript
224
+ try
225
+ remember value as get "https://example.com" timeout 5000
226
+ recover as error
227
+ show message of error
228
+ finally
229
+ show "finished"
230
+
231
+ retry 3 times every 1 second
232
+ show "retry"
233
+ done
234
+ ```
235
+
236
+ Concurrency helpers are `allOf`, `anyOf`, `settledOf`, and `withTimeout`.
237
+ Recurring blocks are `every 5 minutes ... done` and
238
+ `schedule "0 * * * *" ... done`.
239
+
240
+ ## AI providers
241
+
242
+ `chat(model, messages, options)` and `embedText(model, text, options)` use an
243
+ OpenAI-compatible API. Provider presets select safe defaults for the endpoint
244
+ and environment variable:
245
+
246
+ | Provider | API key | Default base |
247
+ | --- | --- | --- |
248
+ | `openai` | `OPENAI_API_KEY` | `https://api.openai.com/v1` |
249
+ | `groq` | `GROQ_API_KEY` | `https://api.groq.com/openai/v1` |
250
+ | `openrouter` | `OPENROUTER_API_KEY` | `https://openrouter.ai/api/v1` |
251
+ | `together` | `TOGETHER_API_KEY` | `https://api.together.xyz/v1` |
252
+ | `fireworks` | `FIREWORKS_API_KEY` | `https://api.fireworks.ai/inference/v1` |
253
+ | `deepseek` | `DEEPSEEK_API_KEY` | `https://api.deepseek.com/v1` |
254
+
255
+ ```plainscript
256
+ remember answer as chat("llama-3.3-70b-versatile", "Hello from PlainScript", {
257
+ provider: "groq",
258
+ key: env("GROQ_API_KEY"),
259
+ temperature: 0.2,
260
+ maxTokens: 200
261
+ })
262
+ remember explicit as chatWith("groq", "llama-3.3-70b-versatile", "Hello")
263
+ show answer
264
+ ```
265
+
266
+ `base`, `key`, `headers`, `temperature`, `maxTokens`, and `responseFormat`
267
+ are optional call options. Custom providers can use a provider name plus
268
+ `base` and `key`; the runtime uses `PROVIDER_API_KEY` and
269
+ `PROVIDER_BASE_URL` as defaults. These calls work in ordinary programs,
270
+ routes, jobs, and messaging handlers.
271
+
272
+ ## WebSockets, cache, bots, and OCR
273
+
274
+ ```plainscript
275
+ websocket server on 8080
276
+ when socket connects
277
+ send socket "connected"
278
+ done
279
+ when socket sends message
280
+ broadcast message
281
+ done
282
+ done
283
+
284
+ cache env("REDIS_URL")
285
+ cacheSet("key", "value", 60)
286
+ remember value as cacheGet("key")
287
+ ```
288
+
289
+ Telegram:
290
+
291
+ ```plainscript
292
+ bot env("TELEGRAM_BOT_TOKEN")
293
+ when someone sends "/start"
294
+ reply "Welcome"
295
+ done
296
+ start telegram bot
297
+ ```
298
+
299
+ Inside a Telegram handler, `message`, `text`, `args`, `matches`, `chat`,
300
+ `chatId`, and callback `data` are update context values. Fixed replies use
301
+ `reply "text"`; provider-backed replies can use `chatWith` before `reply`.
302
+ `telegramCall(method, params)` invokes any Telegram Bot API method.
303
+
304
+ WhatsApp uses `whatsapp bot ... done`, with `auth`, `login qr`, `login
305
+ pairing`, and `on message` clauses. OCR uses:
306
+
307
+ ```plainscript
308
+ ocr path of file as text
309
+ ```
310
+
311
+ ## Native tests
312
+
313
+ ```plainscript
314
+ test "addition"
315
+ check add(2, 3) equals 5
316
+ done
317
+ ```
318
+
319
+ Assertions are `equals`, `is`, `contains`, and `raises`.
320
+
321
+ ## CLI
322
+
323
+ ```text
324
+ plainscript check [target]
325
+ plainscript build [file.pln]
326
+ plainscript run <file.pln>
327
+ plainscript start
328
+ plainscript fmt <file.pln>
329
+ plainscript install
330
+ plainscript doctor
331
+ plainscript version
332
+ ```
333
+
334
+ `check` parses imports, generates JavaScript, and validates that output with
335
+ Node's parser without writing files.