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.
- package/README.md +173 -738
- package/compiler/bundler.js +83 -12
- package/compiler/cli.js +74 -27
- package/compiler/dependency-detector.js +11 -0
- package/compiler/generator.js +372 -35
- package/compiler/lexer.js +2 -0
- package/compiler/parser.js +410 -28
- package/compiler/sourcemap.js +142 -0
- package/compiler/version.js +1 -1
- package/docs/CAPABILITY_GAP_AUDIT.md +98 -534
- package/docs/PLAINSCRIPT-SPEC.md +304 -551
- package/docs/index.html +127 -598
- package/docs/website/script.js +185 -1006
- package/docs/website/style.css +220 -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/mongo.pln +33 -0
- 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/string-verbs.pln +16 -0
- 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 +3 -2
package/docs/PLAINSCRIPT-SPEC.md
CHANGED
|
@@ -1,584 +1,337 @@
|
|
|
1
|
-
# PlainScript
|
|
1
|
+
# PlainScript 1.0.3 language specification
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
-
|
|
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
|
-
|
|
14
|
+
The basic 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 keep their content as-is and support `${expression}` interpolation.
|
|
16
25
|
|
|
17
|
-
|
|
26
|
+
## Values and expressions
|
|
18
27
|
|
|
19
|
-
|
|
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
|
-
|
|
39
|
+
English-style 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 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
|
-
|
|
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
|
-
show "Hello"
|
|
202
|
-
done
|
|
85
|
+
Write a function with `make` and return a value with `give`:
|
|
203
86
|
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
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
|
-
|
|
213
|
-
|
|
92
|
+
show add(2, 3)
|
|
93
|
+
```
|
|
214
94
|
|
|
215
|
-
|
|
95
|
+
Function parameters can have simple defaults:
|
|
216
96
|
|
|
217
|
-
|
|
97
|
+
```plainscript
|
|
98
|
+
make greet(name as "friend")
|
|
99
|
+
give `Hello, ${name}`
|
|
100
|
+
done
|
|
101
|
+
```
|
|
218
102
|
|
|
219
|
-
|
|
103
|
+
Aliases like `define`, `function`, `return`, and `give back` also work. Use
|
|
104
|
+
`make` and `give` for the readable form:
|
|
220
105
|
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
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
|
-
|
|
115
|
+
## Control flow
|
|
226
116
|
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
117
|
+
```plainscript
|
|
118
|
+
for each item in items
|
|
119
|
+
show item
|
|
120
|
+
done
|
|
230
121
|
|
|
231
|
-
|
|
122
|
+
for index i from 0 to 2
|
|
123
|
+
show i
|
|
124
|
+
done
|
|
232
125
|
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
126
|
+
while count is less than 3
|
|
127
|
+
count becomes count + 1
|
|
128
|
+
done
|
|
129
|
+
```
|
|
236
130
|
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
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
|
-
|
|
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
|
-
|
|
244
|
-
|
|
245
|
-
done
|
|
143
|
+
remember player as create a Player with name "Ada" and goals 4
|
|
144
|
+
```
|
|
246
145
|
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|