plainscript-lang 1.0.36 → 1.0.362
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 +252 -20
- package/compiler/bundler.js +4 -4
- package/compiler/cli.js +18 -18
- package/compiler/dependency-detector.js +34 -22
- package/compiler/generator.js +326 -196
- package/compiler/lexer.js +49 -39
- package/compiler/parser.js +552 -181
- package/compiler/sourcemap.js +1 -1
- package/compiler/version.js +1 -1
- package/docs/CAPABILITY_GAP_AUDIT.md +2 -2
- package/docs/FB-PROMPT.md +524 -0
- package/docs/GAME-PROMPT.md +56 -55
- package/docs/PLAINSCRIPT-SPEC.md +16 -15
- package/docs/index.html +13 -6
- package/docs/website/script.js +1 -1
- package/docs/website/style.css +3 -3
- package/examples/ai-providers.pln +1 -1
- package/examples/arrays.pln +1 -1
- package/examples/async-errors.pln +2 -1
- package/examples/auth-api.pln +1 -1
- package/examples/auth-sessions.pln +1 -1
- package/examples/basics.pln +1 -1
- package/examples/bots.pln +1 -1
- package/examples/browser-interactive/README.md +3 -3
- package/examples/browser-interactive/src/interactive.pln +1 -1
- package/examples/cache-and-jobs.pln +1 -1
- package/examples/cache-schedule.pln +1 -1
- package/examples/canvas-game/README.md +4 -4
- package/examples/canvas-game/src/game.pln +1 -1
- package/examples/collections.pln +1 -1
- package/examples/concurrency.pln +1 -1
- package/examples/conditions.pln +1 -1
- package/examples/database.pln +1 -1
- package/examples/day2.pln +1 -1
- package/examples/day3.pln +1 -1
- package/examples/deployment.pln +1 -1
- package/examples/email-send.pln +1 -1
- package/examples/error-handling.pln +3 -2
- package/examples/expressions.pln +1 -1
- package/examples/file-uploads.pln +1 -1
- package/examples/files-and-config.pln +1 -1
- package/examples/files.pln +1 -1
- package/examples/football-backend/app.pln +1 -1
- package/examples/functions.pln +1 -1
- package/examples/hello.pln +1 -1
- package/examples/http-client.pln +1 -1
- package/examples/http.pln +1 -1
- package/examples/id-verification/app.pln +1 -1
- package/examples/javascript-library/README.md +6 -6
- package/examples/javascript-library/public/index.html +1 -1
- package/examples/javascript-library/src/interop.pln +1 -1
- package/examples/json.pln +1 -1
- package/examples/loops.pln +1 -1
- package/examples/modules/app.pln +1 -1
- package/examples/modules/main.pln +1 -1
- package/examples/modules/math.pln +1 -1
- package/examples/mongo.pln +1 -1
- package/examples/objects.pln +1 -1
- package/examples/ocr.pln +1 -1
- package/examples/packages.pln +1 -1
- package/examples/record-kinds.pln +1 -1
- package/examples/records.pln +1 -1
- package/examples/rest-api-fetch.pln +1 -1
- package/examples/rest-api.pln +1 -1
- package/examples/scheduled-tasks.pln +1 -1
- package/examples/search-and-filter.pln +1 -1
- package/examples/server.pln +1 -1
- package/examples/sessions-and-cookies.pln +1 -1
- package/examples/sqlite.pln +1 -1
- package/examples/start.pln +1 -1
- package/examples/stdlib.pln +1 -1
- package/examples/string-verbs.pln +1 -1
- package/examples/telegram-ai-bot.pln +1 -1
- package/examples/telegram-bot.pln +1 -1
- package/examples/testing.pln +1 -1
- package/examples/three-dimensional/README.md +2 -2
- package/examples/three-dimensional/src/scene.pln +1 -1
- package/examples/web-api.pln +1 -1
- package/examples/web-app.pln +1 -1
- package/examples/websocket-server.pln +1 -1
- package/examples/websocket.pln +1 -1
- package/examples/whatsapp-bot/pairing.pln +2 -2
- package/examples/whatsapp-bot/qr.pln +2 -2
- package/package.json +11 -12
package/compiler/sourcemap.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
// SourceMap: V3 Source Map generator for PlainScript compiler.
|
|
2
|
-
// Zero external dependencies
|
|
2
|
+
// Zero external dependencies - implements VLQ Base64 encoding.
|
|
3
3
|
|
|
4
4
|
const BASE64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
|
|
5
5
|
|
package/compiler/version.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# PlainScript 1.0.
|
|
1
|
+
# PlainScript 1.0.362 Capability Audit
|
|
2
2
|
|
|
3
3
|
This audit is based on what the compiler actually supports right now.
|
|
4
4
|
If `plainscript check` validates it, it's listed here.
|
|
@@ -126,6 +126,6 @@ find examples -name '*.pln' -exec node compiler/cli.js check {} \;
|
|
|
126
126
|
|
|
127
127
|
## Version Info
|
|
128
128
|
|
|
129
|
-
The release label for this repo is `1.0.
|
|
129
|
+
The release label for this repo is `1.0.362`. It covers the compiler,
|
|
130
130
|
package metadata, website, editor tooling, and browser/game documentation.
|
|
131
131
|
Third-party dependency versions are not tied to this label.
|
|
@@ -0,0 +1,524 @@
|
|
|
1
|
+
# PlainScript General-Purpose Build Prompt
|
|
2
|
+
|
|
3
|
+
This document is the standing guide for an AI coding agent or programmer
|
|
4
|
+
building a serious project with PlainScript. It describes the compiler and
|
|
5
|
+
runtime that are present in this repository. Treat the compiler and the
|
|
6
|
+
checked examples as the source of truth: if a snippet does not pass
|
|
7
|
+
`node compiler/cli.js check <file.pln>`, it is not a PlainScript program yet.
|
|
8
|
+
|
|
9
|
+
## 1. What PlainScript is
|
|
10
|
+
|
|
11
|
+
PlainScript is a line-oriented, intent-oriented language that compiles to
|
|
12
|
+
readable JavaScript. It is designed to express application logic clearly
|
|
13
|
+
while retaining access to the Node.js, browser, and npm ecosystems.
|
|
14
|
+
|
|
15
|
+
PlainScript is not a replacement for every JavaScript library. Its strongest
|
|
16
|
+
general-purpose pattern is:
|
|
17
|
+
|
|
18
|
+
1. keep application intent, state, control flow, and data transformations in
|
|
19
|
+
`.pln` files;
|
|
20
|
+
2. use PlainScript's built-ins for common application concerns;
|
|
21
|
+
3. call JavaScript APIs and npm packages when the platform or ecosystem
|
|
22
|
+
already provides the right implementation;
|
|
23
|
+
4. compile before running or shipping.
|
|
24
|
+
|
|
25
|
+
The compiler does not use an AI model to generate code. Compilation is
|
|
26
|
+
deterministic and produces ordinary JavaScript.
|
|
27
|
+
|
|
28
|
+
## 2. Project shape
|
|
29
|
+
|
|
30
|
+
For a small program, one file is enough:
|
|
31
|
+
|
|
32
|
+
```text
|
|
33
|
+
hello/
|
|
34
|
+
app.pln
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
For a larger application, keep the source and generated output separate:
|
|
38
|
+
|
|
39
|
+
```text
|
|
40
|
+
my-app/
|
|
41
|
+
src/
|
|
42
|
+
app.pln
|
|
43
|
+
domain.pln
|
|
44
|
+
http.pln
|
|
45
|
+
public/
|
|
46
|
+
index.html
|
|
47
|
+
package.json
|
|
48
|
+
plainscript.config.json
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
`plainscript build` discovers `.pln` files under `src/` and writes matching
|
|
52
|
+
`.js` files under `dist/`. With no `src/` directory, the project root is
|
|
53
|
+
scanned. `plainscript.config.json` may set `rootDir`, `outDir`, and `exclude`.
|
|
54
|
+
Generated JavaScript is build output; do not hand-edit it.
|
|
55
|
+
|
|
56
|
+
Use separate source files for browser and server code. Browser code can be
|
|
57
|
+
compiled as a package-free script; server code can use Node built-ins and
|
|
58
|
+
server packages.
|
|
59
|
+
|
|
60
|
+
## 3. Build and run loop
|
|
61
|
+
|
|
62
|
+
The CLI commands are:
|
|
63
|
+
|
|
64
|
+
```text
|
|
65
|
+
node compiler/cli.js check src/app.pln
|
|
66
|
+
node compiler/cli.js build src/app.pln
|
|
67
|
+
node compiler/cli.js build src/app.pln -o public/app.js
|
|
68
|
+
node compiler/cli.js run src/app.pln
|
|
69
|
+
node compiler/cli.js start
|
|
70
|
+
node compiler/cli.js fmt src/app.pln
|
|
71
|
+
node compiler/cli.js doctor
|
|
72
|
+
node compiler/cli.js install
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Use `check` early and often. It parses imports, generates JavaScript, and
|
|
76
|
+
validates the generated syntax without writing build output. Use `build` for
|
|
77
|
+
artifacts and `run` for a one-file Node program. `start` builds the project's
|
|
78
|
+
entry file and runs the generated output.
|
|
79
|
+
|
|
80
|
+
When a project uses npm packages, keep them in `package.json`. The compiler's
|
|
81
|
+
dependency detector reports packages used by `use`, imports, and built-in
|
|
82
|
+
integration statements. The CLI can install detected dependencies, but
|
|
83
|
+
package installation still depends on the Node version, package availability,
|
|
84
|
+
native modules, and the local environment.
|
|
85
|
+
|
|
86
|
+
## 4. Core syntax
|
|
87
|
+
|
|
88
|
+
### Values and assignment
|
|
89
|
+
|
|
90
|
+
PlainScript supports strings, template strings, numbers, booleans, `null`,
|
|
91
|
+
`undefined`, BigInt, arrays, objects, function values, and JavaScript objects
|
|
92
|
+
returned by libraries.
|
|
93
|
+
|
|
94
|
+
```plainscript
|
|
95
|
+
remember name as "Ada"
|
|
96
|
+
let age be 36
|
|
97
|
+
remember tags as ["compiler", "language"]
|
|
98
|
+
remember user as { name: name, active: true }
|
|
99
|
+
name becomes "Grace"
|
|
100
|
+
show `Hello, ${name}`
|
|
101
|
+
show user.name
|
|
102
|
+
show tags[0]
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Use `remember` or `let` for a local binding and `becomes`, `is now`, `set`,
|
|
106
|
+
or `change` for assignment. Destructuring is available for arrays and
|
|
107
|
+
objects:
|
|
108
|
+
|
|
109
|
+
```plainscript
|
|
110
|
+
remember pair as [10, 20]
|
|
111
|
+
remember [first, second] as pair
|
|
112
|
+
show first
|
|
113
|
+
show second
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
### Expressions and conditions
|
|
117
|
+
|
|
118
|
+
Arithmetic uses `+`, `-`, `*`, `/`, `%`, and `**`. Word forms such as `plus`,
|
|
119
|
+
`minus`, `times`, and `divided by` are also supported. Member calls, indexed
|
|
120
|
+
access, optional chaining, nullish coalescing, `new`, `typeof`, `void`, and
|
|
121
|
+
`delete` are available.
|
|
122
|
+
|
|
123
|
+
```plainscript
|
|
124
|
+
remember score as 7 * 6
|
|
125
|
+
if score is at least 40 and name contains "A"
|
|
126
|
+
show "accepted"
|
|
127
|
+
otherwise
|
|
128
|
+
show "review"
|
|
129
|
+
done
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Conditions support equality, ordering, string predicates, `between`,
|
|
133
|
+
`instanceof`, property checks, and `and`, `or`, and `not`. Inline conditional
|
|
134
|
+
expressions use `choosing ... then ... otherwise ...`.
|
|
135
|
+
|
|
136
|
+
### Functions, closures, and generators
|
|
137
|
+
|
|
138
|
+
```plainscript
|
|
139
|
+
make add(a, b)
|
|
140
|
+
give a + b
|
|
141
|
+
done
|
|
142
|
+
|
|
143
|
+
make greet(name as "friend")
|
|
144
|
+
give `Hello, ${name}`
|
|
145
|
+
done
|
|
146
|
+
|
|
147
|
+
show add(2, 3)
|
|
148
|
+
show greet()
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Functions may capture values from their surrounding scope, accept rest
|
|
152
|
+
parameters, and destructure parameters. `yield` turns a function into a
|
|
153
|
+
JavaScript generator:
|
|
154
|
+
|
|
155
|
+
```plainscript
|
|
156
|
+
make countUp(limit)
|
|
157
|
+
remember i as 0
|
|
158
|
+
while i is less than limit
|
|
159
|
+
i becomes i + 1
|
|
160
|
+
yield i
|
|
161
|
+
done
|
|
162
|
+
done
|
|
163
|
+
|
|
164
|
+
remember values as countUp(3)
|
|
165
|
+
show values.next().value
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### Control flow and collections
|
|
169
|
+
|
|
170
|
+
```plainscript
|
|
171
|
+
for each item in ["a", "b", "c"]
|
|
172
|
+
show item
|
|
173
|
+
done
|
|
174
|
+
|
|
175
|
+
remember count as 0
|
|
176
|
+
while count is less than 3
|
|
177
|
+
count becomes count + 1
|
|
178
|
+
done
|
|
179
|
+
|
|
180
|
+
for index i from 0 to 3
|
|
181
|
+
show i
|
|
182
|
+
done
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
`break` and `continue` work inside loops. The standard library includes
|
|
186
|
+
collection and text helpers such as `length`, `first`, `last`, `range`,
|
|
187
|
+
`sort`, `reverse`, `unique`, `sum`, `flatten`, `groupBy`, `paginate`, `split`,
|
|
188
|
+
`join`, `trim`, `replace`, `startsWith`, and `endsWith`. These helpers return
|
|
189
|
+
ordinary JavaScript values.
|
|
190
|
+
|
|
191
|
+
Record kinds are useful when a domain object has declared fields:
|
|
192
|
+
|
|
193
|
+
```plainscript
|
|
194
|
+
define a kind called "Player" with
|
|
195
|
+
name is ""
|
|
196
|
+
score is 0
|
|
197
|
+
done
|
|
198
|
+
|
|
199
|
+
remember player as create a Player with name "Ada" and score 4
|
|
200
|
+
show player.name
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
## 5. Modules and npm interoperability
|
|
204
|
+
|
|
205
|
+
Local PlainScript modules are bundled in dependency order:
|
|
206
|
+
|
|
207
|
+
```plainscript
|
|
208
|
+
import "./domain.pln"
|
|
209
|
+
import { add } from "./math.pln"
|
|
210
|
+
show add(2, 3)
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Use explicit exports when a module's public surface matters:
|
|
214
|
+
|
|
215
|
+
```plainscript
|
|
216
|
+
make add(a, b)
|
|
217
|
+
give a + b
|
|
218
|
+
done
|
|
219
|
+
export add
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Circular local imports are rejected. Relative imports may omit the `.pln`
|
|
223
|
+
extension and may resolve an `index.pln` or `app.pln` entry in a directory.
|
|
224
|
+
|
|
225
|
+
Use an npm package directly:
|
|
226
|
+
|
|
227
|
+
```plainscript
|
|
228
|
+
use path
|
|
229
|
+
remember file as path.join("data", "items.json")
|
|
230
|
+
show path.basename(file)
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
Packages with JavaScript identifiers can be bound automatically. Packages
|
|
234
|
+
whose names are not valid identifiers should use an alias or a named import:
|
|
235
|
+
|
|
236
|
+
```plainscript
|
|
237
|
+
use node-fetch as fetcher
|
|
238
|
+
remember result as fetcher("https://example.com")
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
The exact package name and export shape remain the npm package's contract.
|
|
242
|
+
PlainScript passes values into JavaScript and receives values back; it does
|
|
243
|
+
not normalize every library API.
|
|
244
|
+
|
|
245
|
+
The `bring`/`import` forms can import a namespace, default export, or named
|
|
246
|
+
exports from a non-local package. Use `new Type(...)` for JavaScript
|
|
247
|
+
constructors, member chains for objects, and callbacks in the same places
|
|
248
|
+
the JavaScript API expects them.
|
|
249
|
+
|
|
250
|
+
## 6. Async and event-driven programming
|
|
251
|
+
|
|
252
|
+
PlainScript propagates asynchronous requirements through functions and
|
|
253
|
+
handlers. Use `wait for` or `await` around a promise:
|
|
254
|
+
|
|
255
|
+
```plainscript
|
|
256
|
+
make loadProfile(id)
|
|
257
|
+
wait for sleep(10)
|
|
258
|
+
give { id: id, ready: true }
|
|
259
|
+
done
|
|
260
|
+
|
|
261
|
+
remember profile as wait for loadProfile(7)
|
|
262
|
+
show profile.ready
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
Async built-ins include promise-aware HTTP requests, database operations,
|
|
266
|
+
mail, OCR, AI helpers, browser asset loading, and `sleep`. Promise
|
|
267
|
+
combinators are available as `all of`, `any of`, `settled of`, and
|
|
268
|
+
`withTimeout`. `run background` schedules work without blocking the current
|
|
269
|
+
path.
|
|
270
|
+
|
|
271
|
+
```plainscript
|
|
272
|
+
make fetchItem(name)
|
|
273
|
+
wait for sleep(5)
|
|
274
|
+
give name
|
|
275
|
+
done
|
|
276
|
+
|
|
277
|
+
remember results as all of [fetchItem("one"), fetchItem("two")]
|
|
278
|
+
show results[0]
|
|
279
|
+
show results[1]
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
Timers and scheduled work use `after`, `every`, `schedule`, and
|
|
283
|
+
`run background`. Event-driven features use `when`, `emit`, WebSocket
|
|
284
|
+
handlers, browser event listeners, and the event APIs supplied by imported
|
|
285
|
+
JavaScript libraries.
|
|
286
|
+
|
|
287
|
+
Errors are ordinary JavaScript exceptions. Handle them explicitly:
|
|
288
|
+
|
|
289
|
+
```plainscript
|
|
290
|
+
try
|
|
291
|
+
remember response as get "https://example.com" timeout 5000
|
|
292
|
+
show response.status
|
|
293
|
+
recover as err
|
|
294
|
+
show message of err
|
|
295
|
+
finally
|
|
296
|
+
show "request complete"
|
|
297
|
+
done
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
`retry ... done` provides bounded retry behavior. Errors thrown inside a
|
|
301
|
+
PlainScript callback or imported JavaScript callback remain part of the same
|
|
302
|
+
exception path, so validate error boundaries in tests.
|
|
303
|
+
|
|
304
|
+
## 7. Files, data, and system integration
|
|
305
|
+
|
|
306
|
+
PlainScript provides synchronous file helpers for simple scripts and data
|
|
307
|
+
pipelines:
|
|
308
|
+
|
|
309
|
+
```plainscript
|
|
310
|
+
remember input as readFile("input.json")
|
|
311
|
+
remember data as jsonDecode(input)
|
|
312
|
+
remember names as data
|
|
313
|
+
gather each item in names giving item.name
|
|
314
|
+
writeFile("names.json", jsonEncode(names))
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
There are helpers for bytes, append/copy/move/delete, folders, file existence,
|
|
318
|
+
JSON encoding/decoding, environment variables, UUIDs, hashing, and dates.
|
|
319
|
+
For more specialized Node APIs, use `use fs`, `use path`, `use crypto`,
|
|
320
|
+
`use child_process`, streams, buffers, typed arrays, or another npm package.
|
|
321
|
+
|
|
322
|
+
Process execution, exit codes, stdin/stdout/stderr, and OS-specific behavior
|
|
323
|
+
belong to the Node API used by the program. Keep those calls behind a small
|
|
324
|
+
PlainScript module so the rest of the application stays portable.
|
|
325
|
+
|
|
326
|
+
## 8. HTTP and backend applications
|
|
327
|
+
|
|
328
|
+
An Express-backed application can be expressed directly:
|
|
329
|
+
|
|
330
|
+
```plainscript
|
|
331
|
+
web app
|
|
332
|
+
allow cors
|
|
333
|
+
|
|
334
|
+
route get "/health"
|
|
335
|
+
reply json
|
|
336
|
+
ok is true
|
|
337
|
+
done
|
|
338
|
+
done
|
|
339
|
+
|
|
340
|
+
route post "/items"
|
|
341
|
+
remember missing as validate("name")
|
|
342
|
+
if length(missing) is greater than 0
|
|
343
|
+
status 400
|
|
344
|
+
reply json
|
|
345
|
+
errors is missing
|
|
346
|
+
done
|
|
347
|
+
otherwise
|
|
348
|
+
reply json
|
|
349
|
+
name is body("name")
|
|
350
|
+
done
|
|
351
|
+
done
|
|
352
|
+
done
|
|
353
|
+
|
|
354
|
+
start 3000
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
Supported route methods are `get`, `post`, `put`, `patch`, and `delete`.
|
|
358
|
+
Request data can be read with `body`, `param`, `query`, `header`, upload
|
|
359
|
+
helpers, and the route-specific request forms documented in
|
|
360
|
+
`docs/PLAINSCRIPT-SPEC.md`. Responses can be text, JSON, files, redirects,
|
|
361
|
+
or explicit status responses.
|
|
362
|
+
|
|
363
|
+
The backend surface also includes static folders, sessions, cookies, API key
|
|
364
|
+
checks, rate limiting, CORS, validation, and fallback routes. These are
|
|
365
|
+
convenience generators over Express middleware; for middleware or server
|
|
366
|
+
features not covered by the friendly syntax, use Express/npm directly.
|
|
367
|
+
|
|
368
|
+
The HTTP client supports `get`, `post`, `put`, `patch`, and `delete` with
|
|
369
|
+
options such as headers, JSON bodies, and timeouts. Check status and error
|
|
370
|
+
behavior at the application boundary; network failures are not silently
|
|
371
|
+
converted into successful responses.
|
|
372
|
+
|
|
373
|
+
## 9. Databases and external services
|
|
374
|
+
|
|
375
|
+
SQLite supports a native driver and a WebAssembly fallback:
|
|
376
|
+
|
|
377
|
+
```plainscript
|
|
378
|
+
database "app.db" using "wasm"
|
|
379
|
+
execute
|
|
380
|
+
CREATE TABLE items (name TEXT)
|
|
381
|
+
done
|
|
382
|
+
insert
|
|
383
|
+
INSERT INTO items (name) VALUES ({name})
|
|
384
|
+
done
|
|
385
|
+
remember name as "Ada"
|
|
386
|
+
remember items as query
|
|
387
|
+
SELECT name FROM items
|
|
388
|
+
done
|
|
389
|
+
show items
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
SQL block placeholders are bound parameters, not string interpolation. Use
|
|
393
|
+
transactions for related writes. PostgreSQL and MongoDB are generated through
|
|
394
|
+
their JavaScript drivers, and asynchronous query behavior remains visible in
|
|
395
|
+
the generated program.
|
|
396
|
+
|
|
397
|
+
Email, Redis/in-memory cache, OCR, Telegram, WhatsApp, AI provider helpers,
|
|
398
|
+
and scheduled jobs are available as integration layers. They require the
|
|
399
|
+
corresponding package and service configuration. Credentials belong in
|
|
400
|
+
environment variables or the deployment's secret store, never in source.
|
|
401
|
+
|
|
402
|
+
For an unsupported provider, prefer `fetch`, the provider's npm SDK, or a
|
|
403
|
+
small external service instead of adding project-specific compiler syntax.
|
|
404
|
+
|
|
405
|
+
## 10. Browser, graphics, and multimedia
|
|
406
|
+
|
|
407
|
+
Package-free generated output can run from a normal browser script. A static
|
|
408
|
+
HTML shell can load the compiled file:
|
|
409
|
+
|
|
410
|
+
```html
|
|
411
|
+
<canvas id="game" width="640" height="480"></canvas>
|
|
412
|
+
<script src="game.js"></script>
|
|
413
|
+
```
|
|
414
|
+
|
|
415
|
+
PlainScript can call browser globals and libraries:
|
|
416
|
+
|
|
417
|
+
```plainscript
|
|
418
|
+
remember canvas as document.getElementById("game")
|
|
419
|
+
remember ctx as canvas.getContext("2d")
|
|
420
|
+
ctx.fillStyle becomes "black"
|
|
421
|
+
ctx.fillRect(0, 0, 640, 480)
|
|
422
|
+
|
|
423
|
+
when document "keydown" happens as event
|
|
424
|
+
show event.key
|
|
425
|
+
done
|
|
426
|
+
|
|
427
|
+
every frame
|
|
428
|
+
ctx.clearRect(0, 0, 640, 480)
|
|
429
|
+
done
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
Browser helpers cover DOM selection, HTML parsing, pointer coordinates,
|
|
433
|
+
gamepads, dropped files, image/audio loading, JSON/byte fetches, data URLs,
|
|
434
|
+
Web Audio, and WebGL shader/program/buffer helpers. WebSocket clients can use
|
|
435
|
+
the browser's `WebSocket` object.
|
|
436
|
+
|
|
437
|
+
Three.js, canvas libraries, WebGL/WebGPU libraries, audio/video APIs, image
|
|
438
|
+
processors, and rendering engines should remain JavaScript dependencies.
|
|
439
|
+
Load a browser-global library before the compiled script or use a browser
|
|
440
|
+
bundler for npm imports. PlainScript does not provide a complete graphics or
|
|
441
|
+
game engine.
|
|
442
|
+
|
|
443
|
+
## 11. Testing and verification
|
|
444
|
+
|
|
445
|
+
Start with compiler validation:
|
|
446
|
+
|
|
447
|
+
```text
|
|
448
|
+
node compiler/cli.js check src/app.pln
|
|
449
|
+
npm test
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
PlainScript also has a native test DSL:
|
|
453
|
+
|
|
454
|
+
```plainscript
|
|
455
|
+
test "addition"
|
|
456
|
+
check 2 + 2 equals 4
|
|
457
|
+
done
|
|
458
|
+
```
|
|
459
|
+
|
|
460
|
+
Use regular Node tests for integration boundaries such as real HTTP servers,
|
|
461
|
+
browser harnesses, database drivers, network services, package exports, and
|
|
462
|
+
process behavior. Add a representative example when a capability crosses
|
|
463
|
+
multiple layers; an isolated generator assertion is not enough.
|
|
464
|
+
|
|
465
|
+
For every new feature, check:
|
|
466
|
+
|
|
467
|
+
- synchronous and asynchronous callers;
|
|
468
|
+
- errors inside callbacks and across module boundaries;
|
|
469
|
+
- promise ordering and timeouts;
|
|
470
|
+
- generated JavaScript syntax;
|
|
471
|
+
- browser versus Node globals;
|
|
472
|
+
- missing environment configuration;
|
|
473
|
+
- package detection and installation;
|
|
474
|
+
- malformed source and useful diagnostics;
|
|
475
|
+
- backwards compatibility with existing examples.
|
|
476
|
+
|
|
477
|
+
## 12. Common mistakes
|
|
478
|
+
|
|
479
|
+
- Do not claim a snippet works without running `plainscript check`.
|
|
480
|
+
- Do not put `require()` in a browser bundle unless a bundler is handling it.
|
|
481
|
+
- Do not assume an npm package's default export is callable; verify its API.
|
|
482
|
+
- Do not use SQL string concatenation when a bound placeholder is available.
|
|
483
|
+
- Do not put API keys, database URLs, or session secrets in `.pln` files.
|
|
484
|
+
- Do not use server-only globals such as `process` or `fs` in browser code.
|
|
485
|
+
- Do not treat an async function as synchronous just because its source reads
|
|
486
|
+
naturally; await its result at the boundary.
|
|
487
|
+
- Do not create circular local imports.
|
|
488
|
+
- Do not edit generated files instead of the `.pln` source.
|
|
489
|
+
- Do not add compiler syntax for a capability already exposed cleanly by an
|
|
490
|
+
npm package or browser API.
|
|
491
|
+
|
|
492
|
+
## 13. What PlainScript should own
|
|
493
|
+
|
|
494
|
+
PlainScript is a good home for application flow, domain rules, validation,
|
|
495
|
+
data shaping, orchestration, route handlers, error handling, and the glue
|
|
496
|
+
between services. Its line-oriented syntax is especially useful for readable
|
|
497
|
+
business logic and small-to-medium service modules.
|
|
498
|
+
|
|
499
|
+
Delegate mature platform implementations to JavaScript/npm: database drivers,
|
|
500
|
+
HTTP clients, graphics engines, codecs, cloud SDKs, model runtimes, and
|
|
501
|
+
specialized algorithms. PlainScript should make those systems usable without
|
|
502
|
+
turning each one into a proprietary language feature.
|
|
503
|
+
|
|
504
|
+
## 14. Current limitations
|
|
505
|
+
|
|
506
|
+
- The compiler targets JavaScript; runtime behavior follows the Node or
|
|
507
|
+
browser version executing the generated code.
|
|
508
|
+
- Package installation can be blocked by the environment or by a package's
|
|
509
|
+
native-module and Node-version requirements.
|
|
510
|
+
- Browser npm imports need a bundler; package-free output is the simplest
|
|
511
|
+
browser deployment path.
|
|
512
|
+
- External services still require their own credentials, network access,
|
|
513
|
+
quotas, and operational handling.
|
|
514
|
+
- PostgreSQL, MongoDB, Redis, mail, AI, OCR, Telegram, WhatsApp, and similar
|
|
515
|
+
integrations are adapters around third-party packages, not local emulators.
|
|
516
|
+
- The language does not provide static type checking or a separate memory
|
|
517
|
+
safety model; use JavaScript tooling and runtime validation where needed.
|
|
518
|
+
- Cancellation, distributed coordination, and streaming semantics depend on
|
|
519
|
+
the underlying JavaScript API. Design those boundaries explicitly.
|
|
520
|
+
|
|
521
|
+
When a proposed feature falls outside this guide, first test whether existing
|
|
522
|
+
PlainScript syntax plus a JavaScript or npm API is enough. Only add a language
|
|
523
|
+
feature when the gap is real, broadly reusable, and worth its compatibility
|
|
524
|
+
cost.
|