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.
- package/README.md +194 -736
- package/compiler/cli.js +13 -17
- package/compiler/generator.js +93 -21
- package/compiler/version.js +1 -1
- package/docs/CAPABILITY_GAP_AUDIT.md +98 -536
- package/docs/PLAINSCRIPT-SPEC.md +308 -557
- package/docs/index.html +101 -599
- package/docs/website/script.js +59 -1029
- package/docs/website/style.css +74 -656
- package/examples/ai-providers.pln +7 -0
- package/examples/arrays.pln +4 -12
- package/examples/async-errors.pln +18 -0
- package/examples/auth-api.pln +3 -50
- package/examples/auth-sessions.pln +32 -0
- package/examples/basics.pln +14 -0
- package/examples/bots.pln +13 -0
- package/examples/cache-and-jobs.pln +6 -28
- package/examples/cache-schedule.pln +22 -0
- package/examples/collections.pln +15 -0
- package/examples/concurrency.pln +12 -43
- package/examples/conditions.pln +22 -0
- package/examples/database.pln +6 -39
- package/examples/day2.pln +6 -6
- package/examples/day3.pln +4 -10
- package/examples/deployment.pln +3 -9
- package/examples/email-send.pln +3 -22
- package/examples/error-handling.pln +6 -54
- package/examples/expressions.pln +7 -40
- package/examples/file-uploads.pln +5 -34
- package/examples/files-and-config.pln +5 -46
- package/examples/files.pln +12 -0
- package/examples/football-backend/app.pln +21 -20
- package/examples/functions.pln +17 -0
- package/examples/hello.pln +2 -3
- package/examples/http-client.pln +3 -44
- package/examples/http.pln +11 -0
- package/examples/id-verification/app.pln +4 -3
- package/examples/id-verification/make-sample-id.js +29 -42
- package/examples/json.pln +11 -0
- package/examples/loops.pln +13 -11
- package/examples/modules/app.pln +3 -16
- package/examples/modules/main.pln +4 -0
- package/examples/modules/math.pln +5 -16
- package/examples/objects.pln +3 -11
- package/examples/ocr.pln +22 -0
- package/examples/packages.pln +6 -0
- package/examples/record-kinds.pln +6 -42
- package/examples/records.pln +15 -0
- package/examples/rest-api-fetch.pln +6 -90
- package/examples/rest-api.pln +5 -65
- package/examples/scheduled-tasks.pln +4 -23
- package/examples/search-and-filter.pln +4 -34
- package/examples/server.pln +5 -24
- package/examples/sessions-and-cookies.pln +4 -50
- package/examples/sqlite.pln +23 -0
- package/examples/start.pln +2 -2
- package/examples/stdlib.pln +4 -41
- package/examples/telegram-ai-bot.pln +19 -0
- package/examples/telegram-bot.pln +4 -40
- package/examples/testing.pln +13 -0
- package/examples/web-api.pln +27 -0
- package/examples/web-app.pln +4 -16
- package/examples/websocket-server.pln +5 -26
- package/examples/websocket.pln +13 -0
- package/examples/whatsapp-bot/pairing.pln +4 -5
- package/examples/whatsapp-bot/qr.pln +7 -3
- package/package.json +2 -2
package/docs/PLAINSCRIPT-SPEC.md
CHANGED
|
@@ -1,584 +1,335 @@
|
|
|
1
|
-
# PlainScript
|
|
1
|
+
# PlainScript 1.0.3-beta language specification
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
-
|
|
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
|
-
|
|
14
|
+
The canonical declaration forms are:
|
|
12
15
|
|
|
13
|
-
|
|
16
|
+
```plainscript
|
|
17
|
+
remember name as "Ada"
|
|
18
|
+
let age be 36
|
|
19
|
+
name becomes "Grace"
|
|
20
|
+
show name
|
|
21
|
+
```
|
|
14
22
|
|
|
15
|
-
|
|
23
|
+
Comments begin with `//`. Double-quoted strings support escapes. Backtick
|
|
24
|
+
strings preserve content and support `${expression}` interpolation.
|
|
16
25
|
|
|
17
|
-
|
|
26
|
+
## Values and expressions
|
|
18
27
|
|
|
19
|
-
|
|
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
|
-
|
|
39
|
+
English collection expressions:
|
|
24
40
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
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
|
-
|
|
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
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
|
87
|
-
|
|
88
|
-
| `is
|
|
89
|
-
| `is
|
|
90
|
-
| `
|
|
91
|
-
| `
|
|
92
|
-
| `
|
|
93
|
-
| `
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
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
|
-
|
|
201
|
-
|
|
202
|
-
|
|
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
|
-
|
|
213
|
-
|
|
90
|
+
show add(2, 3)
|
|
91
|
+
```
|
|
214
92
|
|
|
215
|
-
|
|
93
|
+
Function parameters can have simple defaults:
|
|
216
94
|
|
|
217
|
-
|
|
95
|
+
```plainscript
|
|
96
|
+
make greet(name as "friend")
|
|
97
|
+
give `Hello, ${name}`
|
|
98
|
+
done
|
|
99
|
+
```
|
|
218
100
|
|
|
219
|
-
|
|
101
|
+
Aliases `define`, `function`, `return`, and `give back` are implemented. The
|
|
102
|
+
readable declaration form is:
|
|
220
103
|
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
104
|
+
```plainscript
|
|
105
|
+
make add(a, b)
|
|
106
|
+
give a + b
|
|
107
|
+
done
|
|
108
|
+
```
|
|
224
109
|
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
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
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
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
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
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
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
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.
|