plainscript-lang 1.0.0 → 1.0.2

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 (52) hide show
  1. package/README.md +157 -150
  2. package/compiler/bundler.js +2 -2
  3. package/compiler/cli.js +172 -65
  4. package/compiler/formatter.js +1 -1
  5. package/compiler/generator.js +905 -184
  6. package/compiler/lexer.js +128 -54
  7. package/compiler/parser.js +1075 -155
  8. package/compiler/version.js +1 -1
  9. package/docs/CAPABILITY_GAP_AUDIT.md +131 -30
  10. package/docs/PLAINSCRIPT-SPEC.md +584 -0
  11. package/docs/index.html +48 -52
  12. package/docs/website/script.js +110 -24
  13. package/docs/website/style.css +4 -4
  14. package/examples/arrays.pln +12 -0
  15. package/examples/{auth-api.ps → auth-api.pln} +3 -3
  16. package/examples/{cache-and-jobs.ps → cache-and-jobs.pln} +1 -1
  17. package/examples/{concurrency.ps → concurrency.pln} +8 -8
  18. package/examples/{database.ps → database.pln} +1 -1
  19. package/examples/{deployment.ps → deployment.pln} +2 -2
  20. package/examples/{email-send.ps → email-send.pln} +1 -1
  21. package/examples/{error-handling.ps → error-handling.pln} +8 -7
  22. package/examples/{expressions.ps → expressions.pln} +1 -1
  23. package/examples/{file-uploads.ps → file-uploads.pln} +4 -4
  24. package/examples/{files-and-config.ps → files-and-config.pln} +4 -4
  25. package/examples/football-backend/{app.ps → app.pln} +2 -2
  26. package/examples/{http-client.ps → http-client.pln} +18 -18
  27. package/examples/id-verification/{app.ps → app.pln} +1 -1
  28. package/examples/{loops.ps → loops.pln} +2 -3
  29. package/examples/modules/{app.ps → app.pln} +4 -4
  30. package/examples/modules/{math.ps → math.pln} +1 -1
  31. package/examples/{record-kinds.ps → record-kinds.pln} +4 -4
  32. package/examples/{rest-api-fetch.ps → rest-api-fetch.pln} +1 -1
  33. package/examples/{rest-api.ps → rest-api.pln} +5 -5
  34. package/examples/{scheduled-tasks.ps → scheduled-tasks.pln} +2 -2
  35. package/examples/{search-and-filter.ps → search-and-filter.pln} +5 -5
  36. package/examples/{sessions-and-cookies.ps → sessions-and-cookies.pln} +2 -2
  37. package/examples/start.pln +2 -0
  38. package/examples/{stdlib.ps → stdlib.pln} +2 -2
  39. package/examples/{telegram-bot.ps → telegram-bot.pln} +2 -2
  40. package/examples/{websocket-server.ps → websocket-server.pln} +1 -1
  41. package/package.json +2 -2
  42. package/docs/PLINJS_SPEC.md +0 -1151
  43. package/examples/arrays.ps +0 -13
  44. package/examples/start.ps +0 -2
  45. /package/examples/{day2.ps → day2.pln} +0 -0
  46. /package/examples/{day3.ps → day3.pln} +0 -0
  47. /package/examples/{hello.ps → hello.pln} +0 -0
  48. /package/examples/{objects.ps → objects.pln} +0 -0
  49. /package/examples/{server.ps → server.pln} +0 -0
  50. /package/examples/{web-app.ps → web-app.pln} +0 -0
  51. /package/examples/whatsapp-bot/{pairing.ps → pairing.pln} +0 -0
  52. /package/examples/whatsapp-bot/{qr.ps → qr.pln} +0 -0
@@ -0,0 +1,584 @@
1
+ # PlainScript Language Specification (v2.4)
2
+
3
+ Version: 2.4
4
+ Status: Stable
5
+ File Extension: .pln
6
+
7
+ Tagline: "When even a simple sentence can be code."
8
+
9
+ ---
10
+
11
+ ## Mission
12
+
13
+ PlainScript is an Intent-Oriented Programming Language (IOPL).
14
+
15
+ Its goal is to let developers describe WHAT they want while the compiler decides HOW JavaScript should implement it.
16
+
17
+ PlainScript is designed to be: beginner-friendly, readable, predictable, consistent, and easy to teach.
18
+
19
+ Every keyword should be understandable by a 12-year-old.
20
+
21
+ ---
22
+
23
+ ## Core Principles
24
+
25
+ 1. One way to do everything.
26
+ 2. Readability over fewer characters.
27
+ 3. Keywords never have aliases.
28
+ 4. Error messages should teach.
29
+ 5. JavaScript is an implementation detail.
30
+ 6. Code should read like documentation.
31
+
32
+ ---
33
+
34
+ ## Comments
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
+ ---
69
+
70
+ ## Conditions
71
+
72
+ when age is 18
73
+ show "Adult"
74
+ otherwise
75
+ show "Minor"
76
+ done
77
+
78
+ when age is 18
79
+ show "Adult"
80
+ else
81
+ show "Minor"
82
+ done
83
+
84
+ ### Comparison Operators
85
+
86
+ | PlainScript | JavaScript |
87
+ |------------------------------|--------------------|
88
+ | `is` / `is equal to` | `===` |
89
+ | `is not` | `!==` |
90
+ | `is greater than` | `>` |
91
+ | `is above` | `>` |
92
+ | `is less than` | `<` |
93
+ | `is below` | `<` |
94
+ | `is at least` | `>=` |
95
+ | `is at most` | `<=` |
96
+ | `is empty` | `.length === 0` |
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
+ ---
197
+
198
+ ## Functions
199
+
200
+ to greet
201
+ show "Hello"
202
+ done
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
211
+
212
+ greet()
213
+ show add(5, 7)
214
+
215
+ ---
216
+
217
+ ## Loops
218
+
219
+ For each:
220
+
221
+ for each player in players
222
+ show player
223
+ done
224
+
225
+ For every (alias for for each):
226
+
227
+ for every item in basket
228
+ show item
229
+ done
230
+
231
+ For index:
232
+
233
+ for index i from 0 to 9
234
+ show i
235
+ done
236
+
237
+ for index i from 10 to 1
238
+ show i
239
+ done
240
+
241
+ While:
242
+
243
+ while age is less than 18
244
+ set age to age + 1
245
+ done
246
+
247
+ ---
248
+
249
+ ## Collections
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
430
+
431
+ ---
432
+
433
+ ## Exports
434
+
435
+ let configVersion be 3
436
+ export configVersion
437
+
438
+ ---
439
+
440
+ ## Standard Library
441
+
442
+ All built-in functions are available without any `use` or `import` statement.
443
+
444
+ ### Strings & Numbers
445
+
446
+ | PlainScript | JavaScript equivalent |
447
+ |-----------------|-------------------------|
448
+ | `length(x)` | `(x).length` |
449
+ | `uppercase(x)` | `(x).toUpperCase()` |
450
+ | `lowercase(x)` | `(x).toLowerCase()` |
451
+ | `random()` | `Math.random()` |
452
+ | `round(x)` | `Math.round(x)` |
453
+
454
+ ### Time & System
455
+
456
+ | PlainScript | JavaScript equivalent |
457
+ |----------------|----------------------------------------|
458
+ | `time()` | `Date.now()` |
459
+ | `date()` | `new Date().toISOString()` |
460
+ | `sleep(ms)` | `Atomics.wait(...)` (synchronous) |
461
+ | `uuid()` | `require('crypto').randomUUID()` |
462
+ | `env(key)` | `process.env[key]` |
463
+ | `exit(code)` | `process.exit(code)` |
464
+
465
+ ### JSON
466
+
467
+ | PlainScript | JavaScript equivalent |
468
+ |--------------------|-----------------------------|
469
+ | `jsonEncode(x)` | `JSON.stringify(x)` |
470
+ | `jsonDecode(s)` | `JSON.parse(s)` |
471
+
472
+ ---
473
+
474
+ ## Imports
475
+
476
+ import "./math.pln"
477
+ import { helper } from "./util.pln"
478
+
479
+ ---
480
+
481
+ ## Packages
482
+
483
+ use axios
484
+ use node-fetch as fetch
485
+ use left-pad@^1.3.0
486
+ use @scope/package-name
487
+
488
+ ---
489
+
490
+ ## Reserved Keywords
491
+
492
+ let print
493
+ define function give return
494
+ if otherwise else end
495
+ for each every in
496
+ while
497
+ use import include load
498
+ when someone visits
499
+ listen start_on serve_on
500
+ reply respond send_back
501
+ serve serve_static serve_public
502
+ folder
503
+ is above below at least most
504
+ not empty contains
505
+ starts ends with between and or
506
+ web route start run_on
507
+ database connect_database use_database
508
+ query insert update delete execute
509
+ ask prompt
510
+ ocr
511
+ true false null
512
+ try recover retry
513
+ wait
514
+ accept limit allow
515
+ require api key
516
+ enable sessions
517
+ destroy session
518
+ cookie expires
519
+ limit requests
520
+ google oauth
521
+ define kind
522
+ test check export
523
+ debugger
524
+ symbol
525
+ at position has field
526
+ starts as ends as made of
527
+ more than fewer than same as different from
528
+ together fill with
529
+ raise handled by
530
+ choosing then
531
+
532
+ ---
533
+
534
+ ## Built-in Functions (stdlib)
535
+
536
+ ### Concurrency
537
+ - `all of [...]` - Promise.all
538
+ - `any of [...]` - Promise.race
539
+ - `settled of [...]` - Promise.allSettled
540
+ - `wait for <expr>` - await
541
+ - `retry N times every M seconds` - retry with backoff
542
+
543
+ ### Collections
544
+ - `length(x)` - array/string length
545
+ - `first/last` - array access
546
+ - `spread of x` - [...x]
547
+ - `unique(x)` - deduplicate
548
+ - `sort/reverse` - ordering
549
+
550
+ ### Files
551
+ - `read(path)` / `write(data, path)`
552
+ - `fileExists(path)`
553
+
554
+ ### Crypto
555
+ - `sha256(text)` / `base64Encode` / `base64Decode`
556
+
557
+ ### Network
558
+ - `get/post/put/patch/delete "<url>"` - HTTP requests
559
+
560
+ ### Database
561
+ - `database "file"` / `query` / `insert` / `update` / `delete` / `execute`
562
+
563
+ ### Web
564
+ - `web app` / `route` / `start` / `serve folder`
565
+
566
+ ---
567
+
568
+ ## CLI Commands
569
+
570
+ | Command | Description |
571
+ |---------|-------------|
572
+ | `plainscript new <name>` | Scaffold a new project |
573
+ | `plainscript build [file]` | Compile to dist/ |
574
+ | `plainscript run <file.pln>` | Install deps, compile, run |
575
+ | `plainscript check <file.pln>` | Syntax check only |
576
+ | `plainscript fmt <file.pln>` | Format in-place |
577
+ | `plainscript install` | Install detected dependencies |
578
+ | `plainscript start` | Build and run |
579
+ | `plainscript doctor` | Environment health check |
580
+
581
+ ---
582
+
583
+ This document is the single source of truth for PlainScript v2.4.
584
+ Every compiler implementation must follow this specification.