plainscript-lang 1.0.0 → 1.0.2-latest
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +194 -729
- package/compiler/bundler.js +2 -2
- package/compiler/cli.js +182 -79
- package/compiler/dependency-detector.js +5 -0
- package/compiler/formatter.js +1 -1
- package/compiler/generator.js +1083 -206
- package/compiler/lexer.js +130 -54
- package/compiler/parser.js +1117 -156
- package/compiler/version.js +1 -1
- package/docs/CAPABILITY_GAP_AUDIT.md +98 -435
- package/docs/PLAINSCRIPT-SPEC.md +335 -0
- package/docs/index.html +103 -605
- package/docs/website/script.js +59 -943
- package/docs/website/style.css +74 -656
- package/examples/ai-providers.pln +7 -0
- package/examples/arrays.pln +4 -0
- package/examples/async-errors.pln +18 -0
- package/examples/auth-api.pln +9 -0
- 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 +7 -0
- package/examples/cache-schedule.pln +22 -0
- package/examples/collections.pln +15 -0
- package/examples/concurrency.pln +18 -0
- package/examples/conditions.pln +22 -0
- package/examples/database.pln +8 -0
- package/examples/day2.pln +7 -0
- package/examples/day3.pln +5 -0
- package/examples/deployment.pln +6 -0
- package/examples/email-send.pln +3 -0
- package/examples/error-handling.pln +7 -0
- package/examples/expressions.pln +7 -0
- package/examples/file-uploads.pln +10 -0
- package/examples/files-and-config.pln +6 -0
- package/examples/files.pln +12 -0
- package/examples/football-backend/{app.ps → app.pln} +22 -21
- package/examples/functions.pln +17 -0
- package/examples/hello.pln +2 -0
- package/examples/http-client.pln +3 -0
- package/examples/http.pln +11 -0
- package/examples/id-verification/{app.ps → app.pln} +5 -4
- package/examples/id-verification/make-sample-id.js +29 -42
- package/examples/json.pln +11 -0
- package/examples/loops.pln +18 -0
- package/examples/modules/app.pln +3 -0
- package/examples/modules/main.pln +4 -0
- package/examples/modules/math.pln +9 -0
- package/examples/mongo.pln +33 -0
- package/examples/objects.pln +4 -0
- package/examples/ocr.pln +22 -0
- package/examples/packages.pln +6 -0
- package/examples/record-kinds.pln +7 -0
- package/examples/records.pln +15 -0
- package/examples/rest-api-fetch.pln +10 -0
- package/examples/rest-api.pln +8 -0
- package/examples/scheduled-tasks.pln +4 -0
- package/examples/search-and-filter.pln +4 -0
- package/examples/server.pln +6 -0
- package/examples/sessions-and-cookies.pln +8 -0
- package/examples/sqlite.pln +23 -0
- package/examples/start.pln +2 -0
- package/examples/stdlib.pln +4 -0
- package/examples/telegram-ai-bot.pln +19 -0
- package/examples/telegram-bot.pln +6 -0
- package/examples/testing.pln +13 -0
- package/examples/web-api.pln +27 -0
- package/examples/web-app.pln +8 -0
- package/examples/websocket-server.pln +6 -0
- package/examples/websocket.pln +13 -0
- package/examples/whatsapp-bot/{pairing.ps → pairing.pln} +4 -5
- package/examples/whatsapp-bot/qr.pln +12 -0
- package/package.json +3 -2
- package/docs/PLINJS_SPEC.md +0 -1151
- package/examples/arrays.ps +0 -13
- package/examples/auth-api.ps +0 -56
- package/examples/cache-and-jobs.ps +0 -29
- package/examples/concurrency.ps +0 -49
- package/examples/database.ps +0 -41
- package/examples/day2.ps +0 -7
- package/examples/day3.ps +0 -11
- package/examples/deployment.ps +0 -12
- package/examples/email-send.ps +0 -22
- package/examples/error-handling.ps +0 -54
- package/examples/expressions.ps +0 -40
- package/examples/file-uploads.ps +0 -39
- package/examples/files-and-config.ps +0 -47
- package/examples/hello.ps +0 -3
- package/examples/http-client.ps +0 -44
- package/examples/loops.ps +0 -17
- package/examples/modules/app.ps +0 -16
- package/examples/modules/math.ps +0 -20
- package/examples/objects.ps +0 -12
- package/examples/record-kinds.ps +0 -43
- package/examples/rest-api-fetch.ps +0 -94
- package/examples/rest-api.ps +0 -68
- package/examples/scheduled-tasks.ps +0 -23
- package/examples/search-and-filter.ps +0 -34
- package/examples/server.ps +0 -25
- package/examples/sessions-and-cookies.ps +0 -54
- package/examples/start.ps +0 -2
- package/examples/stdlib.ps +0 -41
- package/examples/telegram-bot.ps +0 -42
- package/examples/web-app.ps +0 -20
- package/examples/websocket-server.ps +0 -27
- package/examples/whatsapp-bot/qr.ps +0 -8
|
@@ -0,0 +1,335 @@
|
|
|
1
|
+
# PlainScript 1.0.2-latest language specification
|
|
2
|
+
|
|
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.
|
|
7
|
+
|
|
8
|
+
## Design
|
|
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.
|
|
13
|
+
|
|
14
|
+
The canonical declaration forms are:
|
|
15
|
+
|
|
16
|
+
```plainscript
|
|
17
|
+
remember name as "Ada"
|
|
18
|
+
let age be 36
|
|
19
|
+
name becomes "Grace"
|
|
20
|
+
show name
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Comments begin with `//`. Double-quoted strings support escapes. Backtick
|
|
24
|
+
strings preserve content and support `${expression}` interpolation.
|
|
25
|
+
|
|
26
|
+
## Values and expressions
|
|
27
|
+
|
|
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.
|
|
31
|
+
|
|
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
|
+
```
|
|
38
|
+
|
|
39
|
+
English collection expressions:
|
|
40
|
+
|
|
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
|
+
```
|
|
49
|
+
|
|
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.
|
|
54
|
+
|
|
55
|
+
## Conditions
|
|
56
|
+
|
|
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`.
|
|
82
|
+
|
|
83
|
+
## Functions
|
|
84
|
+
|
|
85
|
+
```plainscript
|
|
86
|
+
make add(a, b)
|
|
87
|
+
give a + b
|
|
88
|
+
done
|
|
89
|
+
|
|
90
|
+
show add(2, 3)
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Function parameters can have simple defaults:
|
|
94
|
+
|
|
95
|
+
```plainscript
|
|
96
|
+
make greet(name as "friend")
|
|
97
|
+
give `Hello, ${name}`
|
|
98
|
+
done
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Aliases `define`, `function`, `return`, and `give back` are implemented. The
|
|
102
|
+
readable declaration form is:
|
|
103
|
+
|
|
104
|
+
```plainscript
|
|
105
|
+
make add(a, b)
|
|
106
|
+
give a + b
|
|
107
|
+
done
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
`yield` creates a generator function. Functions may use `wait for` and other
|
|
111
|
+
async operations.
|
|
112
|
+
|
|
113
|
+
## Control flow
|
|
114
|
+
|
|
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
|
|
123
|
+
|
|
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.
|
|
146
|
+
|
|
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.
|