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.
Files changed (106) hide show
  1. package/README.md +194 -729
  2. package/compiler/bundler.js +2 -2
  3. package/compiler/cli.js +182 -79
  4. package/compiler/dependency-detector.js +5 -0
  5. package/compiler/formatter.js +1 -1
  6. package/compiler/generator.js +1083 -206
  7. package/compiler/lexer.js +130 -54
  8. package/compiler/parser.js +1117 -156
  9. package/compiler/version.js +1 -1
  10. package/docs/CAPABILITY_GAP_AUDIT.md +98 -435
  11. package/docs/PLAINSCRIPT-SPEC.md +335 -0
  12. package/docs/index.html +103 -605
  13. package/docs/website/script.js +59 -943
  14. package/docs/website/style.css +74 -656
  15. package/examples/ai-providers.pln +7 -0
  16. package/examples/arrays.pln +4 -0
  17. package/examples/async-errors.pln +18 -0
  18. package/examples/auth-api.pln +9 -0
  19. package/examples/auth-sessions.pln +32 -0
  20. package/examples/basics.pln +14 -0
  21. package/examples/bots.pln +13 -0
  22. package/examples/cache-and-jobs.pln +7 -0
  23. package/examples/cache-schedule.pln +22 -0
  24. package/examples/collections.pln +15 -0
  25. package/examples/concurrency.pln +18 -0
  26. package/examples/conditions.pln +22 -0
  27. package/examples/database.pln +8 -0
  28. package/examples/day2.pln +7 -0
  29. package/examples/day3.pln +5 -0
  30. package/examples/deployment.pln +6 -0
  31. package/examples/email-send.pln +3 -0
  32. package/examples/error-handling.pln +7 -0
  33. package/examples/expressions.pln +7 -0
  34. package/examples/file-uploads.pln +10 -0
  35. package/examples/files-and-config.pln +6 -0
  36. package/examples/files.pln +12 -0
  37. package/examples/football-backend/{app.ps → app.pln} +22 -21
  38. package/examples/functions.pln +17 -0
  39. package/examples/hello.pln +2 -0
  40. package/examples/http-client.pln +3 -0
  41. package/examples/http.pln +11 -0
  42. package/examples/id-verification/{app.ps → app.pln} +5 -4
  43. package/examples/id-verification/make-sample-id.js +29 -42
  44. package/examples/json.pln +11 -0
  45. package/examples/loops.pln +18 -0
  46. package/examples/modules/app.pln +3 -0
  47. package/examples/modules/main.pln +4 -0
  48. package/examples/modules/math.pln +9 -0
  49. package/examples/mongo.pln +33 -0
  50. package/examples/objects.pln +4 -0
  51. package/examples/ocr.pln +22 -0
  52. package/examples/packages.pln +6 -0
  53. package/examples/record-kinds.pln +7 -0
  54. package/examples/records.pln +15 -0
  55. package/examples/rest-api-fetch.pln +10 -0
  56. package/examples/rest-api.pln +8 -0
  57. package/examples/scheduled-tasks.pln +4 -0
  58. package/examples/search-and-filter.pln +4 -0
  59. package/examples/server.pln +6 -0
  60. package/examples/sessions-and-cookies.pln +8 -0
  61. package/examples/sqlite.pln +23 -0
  62. package/examples/start.pln +2 -0
  63. package/examples/stdlib.pln +4 -0
  64. package/examples/telegram-ai-bot.pln +19 -0
  65. package/examples/telegram-bot.pln +6 -0
  66. package/examples/testing.pln +13 -0
  67. package/examples/web-api.pln +27 -0
  68. package/examples/web-app.pln +8 -0
  69. package/examples/websocket-server.pln +6 -0
  70. package/examples/websocket.pln +13 -0
  71. package/examples/whatsapp-bot/{pairing.ps → pairing.pln} +4 -5
  72. package/examples/whatsapp-bot/qr.pln +12 -0
  73. package/package.json +3 -2
  74. package/docs/PLINJS_SPEC.md +0 -1151
  75. package/examples/arrays.ps +0 -13
  76. package/examples/auth-api.ps +0 -56
  77. package/examples/cache-and-jobs.ps +0 -29
  78. package/examples/concurrency.ps +0 -49
  79. package/examples/database.ps +0 -41
  80. package/examples/day2.ps +0 -7
  81. package/examples/day3.ps +0 -11
  82. package/examples/deployment.ps +0 -12
  83. package/examples/email-send.ps +0 -22
  84. package/examples/error-handling.ps +0 -54
  85. package/examples/expressions.ps +0 -40
  86. package/examples/file-uploads.ps +0 -39
  87. package/examples/files-and-config.ps +0 -47
  88. package/examples/hello.ps +0 -3
  89. package/examples/http-client.ps +0 -44
  90. package/examples/loops.ps +0 -17
  91. package/examples/modules/app.ps +0 -16
  92. package/examples/modules/math.ps +0 -20
  93. package/examples/objects.ps +0 -12
  94. package/examples/record-kinds.ps +0 -43
  95. package/examples/rest-api-fetch.ps +0 -94
  96. package/examples/rest-api.ps +0 -68
  97. package/examples/scheduled-tasks.ps +0 -23
  98. package/examples/search-and-filter.ps +0 -34
  99. package/examples/server.ps +0 -25
  100. package/examples/sessions-and-cookies.ps +0 -54
  101. package/examples/start.ps +0 -2
  102. package/examples/stdlib.ps +0 -41
  103. package/examples/telegram-bot.ps +0 -42
  104. package/examples/web-app.ps +0 -20
  105. package/examples/websocket-server.ps +0 -27
  106. 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.