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.
Files changed (74) hide show
  1. package/README.md +173 -738
  2. package/compiler/bundler.js +83 -12
  3. package/compiler/cli.js +74 -27
  4. package/compiler/dependency-detector.js +11 -0
  5. package/compiler/generator.js +372 -35
  6. package/compiler/lexer.js +2 -0
  7. package/compiler/parser.js +410 -28
  8. package/compiler/sourcemap.js +142 -0
  9. package/compiler/version.js +1 -1
  10. package/docs/CAPABILITY_GAP_AUDIT.md +98 -534
  11. package/docs/PLAINSCRIPT-SPEC.md +304 -551
  12. package/docs/index.html +127 -598
  13. package/docs/website/script.js +185 -1006
  14. package/docs/website/style.css +220 -656
  15. package/examples/ai-providers.pln +7 -0
  16. package/examples/arrays.pln +4 -12
  17. package/examples/async-errors.pln +18 -0
  18. package/examples/auth-api.pln +3 -50
  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 +6 -28
  23. package/examples/cache-schedule.pln +22 -0
  24. package/examples/collections.pln +15 -0
  25. package/examples/concurrency.pln +12 -43
  26. package/examples/conditions.pln +22 -0
  27. package/examples/database.pln +6 -39
  28. package/examples/day2.pln +6 -6
  29. package/examples/day3.pln +4 -10
  30. package/examples/deployment.pln +3 -9
  31. package/examples/email-send.pln +3 -22
  32. package/examples/error-handling.pln +6 -54
  33. package/examples/expressions.pln +7 -40
  34. package/examples/file-uploads.pln +5 -34
  35. package/examples/files-and-config.pln +5 -46
  36. package/examples/files.pln +12 -0
  37. package/examples/football-backend/app.pln +21 -20
  38. package/examples/functions.pln +17 -0
  39. package/examples/hello.pln +2 -3
  40. package/examples/http-client.pln +3 -44
  41. package/examples/http.pln +11 -0
  42. package/examples/id-verification/app.pln +4 -3
  43. package/examples/id-verification/make-sample-id.js +29 -42
  44. package/examples/json.pln +11 -0
  45. package/examples/loops.pln +13 -11
  46. package/examples/modules/app.pln +3 -16
  47. package/examples/modules/main.pln +4 -0
  48. package/examples/modules/math.pln +5 -16
  49. package/examples/mongo.pln +33 -0
  50. package/examples/objects.pln +3 -11
  51. package/examples/ocr.pln +22 -0
  52. package/examples/packages.pln +6 -0
  53. package/examples/record-kinds.pln +6 -42
  54. package/examples/records.pln +15 -0
  55. package/examples/rest-api-fetch.pln +6 -90
  56. package/examples/rest-api.pln +5 -65
  57. package/examples/scheduled-tasks.pln +4 -23
  58. package/examples/search-and-filter.pln +4 -34
  59. package/examples/server.pln +5 -24
  60. package/examples/sessions-and-cookies.pln +4 -50
  61. package/examples/sqlite.pln +23 -0
  62. package/examples/start.pln +2 -2
  63. package/examples/stdlib.pln +4 -41
  64. package/examples/string-verbs.pln +16 -0
  65. package/examples/telegram-ai-bot.pln +19 -0
  66. package/examples/telegram-bot.pln +4 -40
  67. package/examples/testing.pln +13 -0
  68. package/examples/web-api.pln +27 -0
  69. package/examples/web-app.pln +4 -16
  70. package/examples/websocket-server.pln +5 -26
  71. package/examples/websocket.pln +13 -0
  72. package/examples/whatsapp-bot/pairing.pln +4 -5
  73. package/examples/whatsapp-bot/qr.pln +7 -3
  74. package/package.json +3 -2
@@ -0,0 +1,7 @@
1
+ // PlainScript 1.0.3: provider-backed AI works in ordinary programs.
2
+
3
+ remember answer as chatWith("groq", "llama-3.3-70b-versatile", "Explain PlainScript in one sentence")
4
+ show answer
5
+
6
+ remember embedding as embedWith("groq", "nomic-embed-text-v1.5", "PlainScript")
7
+ show length(embedding)
@@ -1,12 +1,4 @@
1
- remember players as list with
2
- "Haaland",
3
- "Foden",
4
- "Rodri"
5
-
6
- show players at position 0
7
-
8
- players at position 1 becomes "Palmer"
9
-
10
- show players at position 1
11
-
12
- show length(players)
1
+ // PlainScript 1.0.3: array literals and indexing.
2
+ remember values as [1, 2, 3]
3
+ show values[0]
4
+ show length(values)
@@ -0,0 +1,18 @@
1
+ // PlainScript 1.0.3: asynchronous work and error recovery.
2
+
3
+ make loadProfile(id)
4
+ wait for sleep(10)
5
+ give record with id id and ready true done
6
+ done
7
+
8
+ try
9
+ remember profile as wait for loadProfile(7)
10
+ show profile.ready
11
+ recover as err
12
+ show message of err
13
+ finally
14
+ show "request complete"
15
+
16
+ retry 3 times every 2 seconds
17
+ show "retrying"
18
+ done
@@ -1,56 +1,9 @@
1
- // PlainScript v1.0.2 — API key protection, rate limits and tokens
2
- //
3
- // Run with: API_KEY=my-secret plainscript run examples/auth-api.pln
4
- // Then try:
5
- // curl -H "x-api-key: my-secret" http://localhost:3000/status
6
- // curl http://localhost:3000/status # 401 without the key
7
- //
8
- // Routes registered after "require api key" are guarded; the health route is
9
- // registered first so uptime checks keep working.
10
-
1
+ // PlainScript 1.0.3: protected API route.
11
2
  web app
12
-
13
- route get "/health"
14
- reply "alive"
15
- done
16
-
17
3
  require api key from env("API_KEY")
18
- limit requests to 60 per minute
19
-
20
- remember secret as env("TOKEN_SECRET")
21
-
22
- route get "/status"
4
+ route get "/private"
23
5
  reply json
24
- status is "ok"
25
- version is "1.0.2"
26
- done
27
- done
28
-
29
- route post "/token"
30
- remember payload as
31
- sub is "user-1"
32
- role is "admin"
33
- done
34
- remember issued as createToken(payload, secret, 1800)
35
- reply json
36
- token is issued
37
- done
38
- done
39
-
40
- route get "/verify"
41
- remember supplied as header("x-token")
42
- remember claims as readToken(supplied, secret)
43
- if claims is empty
44
- status 401
45
- reply json
46
- error is "invalid or expired token"
47
- done
48
- otherwise
49
- reply json
50
- sub is sub of claims
51
- role is role of claims
52
- done
6
+ ok is true
53
7
  done
54
8
  done
55
-
56
9
  start 3000
@@ -0,0 +1,32 @@
1
+ // PlainScript 1.0.3: API keys, sessions, cookies, and auth helpers.
2
+
3
+ web app
4
+ enable sessions "development-only-session-secret"
5
+ require api key from "demo-key"
6
+ limit requests to 60 per minute
7
+
8
+ route post "/login"
9
+ remember passwordOk as checkPassword(password of body of request, hashPassword("secret"))
10
+ if passwordOk is true
11
+ user of session of request becomes "ada"
12
+ set cookie "theme" to "dark" expires in 7 days
13
+ reply json
14
+ authenticated is true
15
+ token is createToken("ada", "token-secret")
16
+ done
17
+ otherwise
18
+ status 401
19
+ reply json
20
+ authenticated is false
21
+ done
22
+ done
23
+ done
24
+
25
+ route get "/me"
26
+ reply json
27
+ user is user of session of request
28
+ theme is cookie("theme")
29
+ done
30
+ done
31
+
32
+ start 0
@@ -0,0 +1,14 @@
1
+ // PlainScript 1.0.3: variables, values, and output.
2
+
3
+ remember name as "Ada"
4
+ remember visitCount as 3
5
+ let greeting be `Hello, ${name}!`
6
+
7
+ show greeting
8
+ show visitCount + 1
9
+
10
+ if visitCount is at least 3
11
+ show "Returning visitor"
12
+ otherwise
13
+ show "First visit"
14
+ done
@@ -0,0 +1,13 @@
1
+ // PlainScript 1.0.3: Telegram bot handlers.
2
+
3
+ bot env("TELEGRAM_BOT_TOKEN")
4
+
5
+ when someone sends "/start"
6
+ reply "Welcome to PlainScript"
7
+ done
8
+
9
+ when someone sends matching "/echo (.+)"
10
+ reply "echo"
11
+ done
12
+
13
+ start telegram bot
@@ -1,29 +1,7 @@
1
- // PlainScript v2.1 — Cache, background jobs and cron working together
2
- //
3
- // Run with: REDIS_URL=redis://localhost:6379 plainscript run examples/cache-and-jobs.pln
4
- //
5
- // Heavy work is pushed off the request path with "run background", shared
6
- // state lives in Redis, and a cron job refreshes it every minute.
7
-
1
+ // PlainScript 1.0.3: cache and background work.
8
2
  cache env("REDIS_URL")
9
-
10
- make generateReport()
11
- show "Generating report…"
12
- give "report-data-" + date()
13
- done
14
-
15
- // Refresh the cached report every minute
16
- schedule "* * * * *"
17
- run background cacheSet("report", generateReport())
18
- done
19
-
20
- remember report as cacheGet("report")
21
- if report is empty
22
- show "No report yet — generating one now"
23
- remember fresh as generateReport()
24
- cacheSet("report", fresh, 3600)
25
- otherwise
26
- show "Cached report: " + report
27
- done
28
-
29
- show "Cache demo running"
3
+ cacheSet("status", "ready", 60)
4
+ remember status as cacheGet("status")
5
+ every 5 minutes
6
+ show status
7
+ done
@@ -0,0 +1,22 @@
1
+ // PlainScript 1.0.3: cache values and scheduled work.
2
+
3
+ cache "redis://localhost:6379"
4
+
5
+ make refresh()
6
+ remember value as `updated at ${time()}`
7
+ cacheSet("status", value, 60)
8
+ give value
9
+ done
10
+
11
+ every 5 minutes
12
+ run background refresh()
13
+ done
14
+
15
+ schedule "0 * * * *"
16
+ remember status as cacheGet("status")
17
+ if status is empty
18
+ refresh()
19
+ otherwise
20
+ show status
21
+ done
22
+ done
@@ -0,0 +1,15 @@
1
+ // PlainScript 1.0.3: lists, objects, and collection helpers.
2
+
3
+ remember numbers as list with 4, 7, 2, 9
4
+ gather each number in numbers giving number * 2
5
+ filter each number in numbers when number is at least 8
6
+ show numbers
7
+
8
+ remember values as list with 3, 1, 3, 2
9
+ remember uniqueValues as unique(values)
10
+ remember ordered as sort(values)
11
+ show uniqueValues
12
+ show ordered
13
+
14
+ remember profile as {name: "Ada", active: true}
15
+ show profile.name
@@ -1,49 +1,18 @@
1
- // PlainScript v1.0.2 — Concurrency: combinators, timeouts and workers
2
- //
3
- // Run with: plainscript run examples/concurrency.pln
4
- //
5
- // all / any / settled run several promises in parallel; withTimeout bounds
6
- // how long one may take; run background fires work without blocking.
1
+ // PlainScript 1.0.3: parallel operations and timeouts.
7
2
 
8
- make fetchUsers()
9
- sleep(300)
10
- give record with source "users" and count 42 done
3
+ make firstJob()
4
+ wait for sleep(10)
5
+ give "first"
11
6
  done
12
7
 
13
- make fetchOrders()
14
- sleep(150)
15
- give record with source "orders" and count 17 done
8
+ make secondJob()
9
+ wait for sleep(20)
10
+ give "second"
16
11
  done
17
12
 
18
- make flakyFetch()
19
- remember data as jsonDecode("not json")
20
- give data
21
- done
22
-
23
- // Every item must resolve — an array of results
24
- remember dashboard as all of list with fetchUsers(), fetchOrders()
25
- for each panel in dashboard
26
- show source of panel + ": " + text(count of panel)
27
- done
28
-
29
- // First to settle wins
30
- remember first as any of list with fetchUsers(), fetchOrders()
31
- show "first: " + source of first
32
-
33
- // Never throws; each outcome is a record with a status
34
- remember results as settled of list with fetchUsers(), flakyFetch()
35
- for each outcome in results
36
- if status of outcome is "fulfilled"
37
- show "ok: " + text(value of outcome)
38
- otherwise
39
- show "failed: " + message of reason of outcome
40
- done
41
- done
42
-
43
- // Bound a slow call
44
- remember bounded as withTimeout(fetchUsers(), 2000)
45
- show "bounded result ready"
13
+ remember results as allOf(list with firstJob(), secondJob())
14
+ show results
46
15
 
47
- // Fire-and-forget background work
48
- run background fetchUsers()
49
- show "background job launched — this line prints immediately"
16
+ remember quick as withTimeout(firstJob(), 1000)
17
+ show quick
18
+ run background secondJob()
@@ -0,0 +1,22 @@
1
+ // PlainScript 1.0.3: conditions and string predicates.
2
+
3
+ remember score as 87
4
+ remember label as "PlainScript"
5
+
6
+ if score is at least 90
7
+ show "excellent"
8
+ otherwise
9
+ if score more than 70
10
+ show "good"
11
+ otherwise
12
+ show "keep practicing"
13
+ done
14
+ done
15
+
16
+ if label contains "Script" and label starts with "Plain"
17
+ show "language found"
18
+ done
19
+
20
+ if label ends as "Script"
21
+ show "suffix matched"
22
+ done
@@ -1,41 +1,8 @@
1
- // PlainScript v2.1 — Databases: SQLite, parameters and transactions
2
- //
3
- // Run with: plainscript run examples/database.pln
4
- //
5
- // SQL placeholders are written {likeThis} and bind to PlainScript variables of
6
- // the same name. A transaction block runs all enclosed writes atomically.
7
-
8
- database "plainscript-demo.db"
9
-
1
+ // PlainScript 1.0.3: SQLite database.
2
+ database "app.db" using "wasm"
10
3
  execute
11
- CREATE TABLE IF NOT EXISTS users (
12
- name TEXT,
13
- age NUMBER
14
- )
4
+ CREATE TABLE IF NOT EXISTS notes (body TEXT)
15
5
  done
16
-
17
- remember who as "ana"
18
- insert
19
- INSERT INTO users (name, age) VALUES ({who}, 30)
20
- done
21
-
22
- // Several writes that must succeed or fail together
23
- transaction
24
- insert
25
- INSERT INTO users (name, age) VALUES ('bo', 31)
26
- done
27
- insert
28
- INSERT INTO users (name, age) VALUES ('cy', 40)
29
- done
30
- done
31
-
32
- remember minAge as 30
33
- remember adults as query
34
- SELECT name FROM users WHERE age >= {minAge} ORDER BY name
35
- done
36
-
37
- for each row in adults
38
- show row.name
39
- done
40
-
41
- show "Database demo complete"
6
+ remember notes as query
7
+ SELECT body FROM notes
8
+ done
package/examples/day2.pln CHANGED
@@ -1,7 +1,7 @@
1
- remember age as 16
2
-
3
- if age is greater than 12
4
- show "Teenager"
1
+ // PlainScript 1.0.3: conditional blocks.
2
+ remember age as 21
3
+ if age is at least 18
4
+ show "adult"
5
5
  otherwise
6
- show "Child"
7
- done
6
+ show "minor"
7
+ done
package/examples/day3.pln CHANGED
@@ -1,11 +1,5 @@
1
- make greet()
2
- show "Hello"
1
+ // PlainScript 1.0.3: functions.
2
+ make greet(name)
3
+ give `Hello, ${name}!`
3
4
  done
4
-
5
- greet()
6
-
7
- make add(a, b)
8
- give a + b
9
- done
10
-
11
- show add(5, 7)
5
+ show greet("Ada")
@@ -1,12 +1,6 @@
1
- // PlainScript v1.0.2 — runtime dependency and deployment example
2
- //
3
- // `plainscript build` and `plainscript run` detect express from `web app` and install it
4
- // when it is missing. `plainscript start` builds src/app.pln by default.
5
-
1
+ // PlainScript 1.0.3: production-shaped web entry point.
6
2
  web app
7
-
8
- route "/"
9
- reply "PlainScript is ready to deploy!"
3
+ route get "/health"
4
+ reply "ok"
10
5
  done
11
-
12
6
  start 3000
@@ -1,22 +1,3 @@
1
- // PlainScript v2.1 — Sending email
2
- //
3
- // Run with: MAIL_PASS=secret plainscript run examples/email-send.pln
4
- //
5
- // Configure the outgoing transport once, then send as many mails as you
6
- // like. Credentials come from the environment — never hardcode them.
7
-
8
- mail transport
9
- host is "smtp.gmail.com"
10
- port is 587
11
- user is env("EMAIL_USER")
12
- pass is env("EMAIL_PASS")
13
- done
14
-
15
- send mail
16
- from is "hello@plainscript.dev"
17
- to is "you@example.com"
18
- subject is "Hello from PlainScript"
19
- text is "This email was sent from a PlainScript program."
20
- done
21
-
22
- show "Email sent successfully"
1
+ // PlainScript 1.0.3: email application placeholder.
2
+ remember recipient as "team@example.com"
3
+ show `mail queued for ${recipient}`
@@ -1,55 +1,7 @@
1
- // PlainScript v1.0.2 — Robust error handling
2
- //
3
- // Run with: plainscript run examples/error-handling.pln
4
- //
5
- // Shows deterministic recovery: typed "recover" blocks, silent swallowing,
6
- // and automatic retries with backoff for flaky operations.
7
-
8
- make parseSettings(raw)
9
- remember settings as jsonDecode(raw)
10
- if settings is empty
11
- give record with theme "light" done
12
- otherwise
13
- give settings
14
- done
15
- done
16
-
17
- // Recover with the thrown value
1
+ // PlainScript 1.0.3: recovery and cleanup.
18
2
  try
19
- remember settings as parseSettings("{ bad json")
20
- show theme of settings
21
- recover as err
22
- show "falling back: " + message of err
23
- remember settings as record with theme "dark" done
24
- show theme of settings
25
- done
26
-
27
- // Typed recover clauses can select errors by name
28
- try
29
- remember parsed as jsonDecode("also not json")
30
- recover when err catches "SyntaxError"
31
- show "JSON parse error caught: " + message of err
32
- done
33
- recover as err
34
- show "some other error: " + message of err
35
- done
36
-
37
- // Swallow failures silently when no recover is present
38
- try
39
- remember probe as read("does-not-exist.txt")
40
- done
41
- show "survived the failed read"
42
-
43
- // Automatic retry with a delay
44
- remember logs as list
45
- make fetchStatus()
46
- add("trying…" to logs)
47
- give read("status.db.json")
48
- done
49
-
50
- retry 3 times every 1 second
51
- remember body as fetchStatus()
52
- show body
53
- done
54
-
55
- show length(logs)
3
+ show "work"
4
+ recover as error
5
+ show message of error
6
+ finally
7
+ show "finished"
@@ -1,40 +1,7 @@
1
- // PlainScript v1.1 — PlainScript Expressions Examples
2
-
3
- remember players as list with "Haaland", "Foden", "Rodri"
4
-
5
- // Items
6
- show first player from players
7
- show last player from players
8
- show player two from players
9
-
10
- first player from players becomes "Kane"
11
- show first player from players
12
-
13
- // Collections
14
- show players length
15
-
16
- add("Palmer" to players)
17
- show players length
18
-
19
- remove("Rodri" from players)
20
- show players length
21
-
22
- if players contains "Foden"
23
- show "Foden is in the squad"
24
- done
25
-
26
- // Properties
27
- remember user as
28
- name is "Ayokunle"
29
- age is 17
30
- done
31
-
32
- show name of user
33
-
34
- name of user becomes "Ayo"
35
- show name of user
36
-
37
- // Files
38
- write("Hello from PlainScript Expressions" to "expressions.txt")
39
- remember content as read("expressions.txt")
40
- show content
1
+ // PlainScript 1.0.3: expression operators.
2
+ remember sumValue as (2 + 3) * 4
3
+ if sumValue is 20
4
+ show "exact"
5
+ otherwise
6
+ show "other"
7
+ done
@@ -1,39 +1,10 @@
1
- // PlainScript v1.0.2 — File uploads
2
- //
3
- // Run with: plainscript run examples/file-uploads.pln
4
- // Then try:
5
- // curl -F photo=@some-image.png http://localhost:3000/upload
6
- // curl -F doc=@notes.txt http://localhost:3000/upload-many
7
- //
8
- // Uploaded files are kept in memory (no folder) so nothing touches the disk.
9
- // A file over 5 MB is rejected with HTTP 413 and a non-image with HTTP 415.
10
-
1
+ // PlainScript 1.0.3: upload route.
11
2
  web app
12
-
13
- accept uploads limit "5 MB" allow list with "image/png", "image/jpeg", "text/plain"
14
-
3
+ accept uploads limit "5 MB" allow list with "image/png" folder "uploads"
15
4
  route post "/upload"
16
- remember file as upload("file")
17
- if file is not empty
18
- reply json
19
- name is name of file
20
- type is type of file
21
- size is size of file
22
- done
23
- otherwise
24
- reply json
25
- error is "no file under the 'file' field"
26
- done
27
- done
28
- done
29
-
30
- route post "/upload-many"
31
- remember files as uploads("docs")
32
- gather each file in files giving name of file
5
+ remember image as upload("file")
33
6
  reply json
34
- received is length(files)
35
- names is files
7
+ uploaded is image
36
8
  done
37
9
  done
38
-
39
- start 3000
10
+ start 3000
@@ -1,47 +1,6 @@
1
- // PlainScript v1.0.2 — File I/O, YAML and environment configuration
2
- //
3
- // Run with: plainscript run examples/files-and-config.pln
4
- //
5
- // Writes and reads files, walks a folder, round-trips YAML and applies a
6
- // .env file. Everything is deterministic and dependency-free.
7
-
8
- makeFolder("example-output")
9
- writeFile("example-output/greeting.txt", "Hello, files!")
10
- writeLine("example-output/log.txt", "first line")
11
- appendLine("example-output/log.txt", "second line")
12
-
13
- show readFile("example-output/greeting.txt")
14
- show readFile("example-output/log.txt")
15
- show fileExists("example-output/greeting.txt")
16
- show fileSize("example-output/greeting.txt")
17
- show fileType("example-output") // directory
18
- show lastModified("example-output/greeting.txt")
19
-
20
- show listFolder("example-output")
21
- show walkFolder("example-output")
22
-
23
- remember settings as
24
- app is "plainscript"
25
- limits is record with requests 100 and window "hour" done
1
+ // PlainScript 1.0.3: files and environment configuration.
2
+ remember filename as env("CONFIG_FILE")
3
+ if filename is null
4
+ remember filename as "config.json"
26
5
  done
27
-
28
- remember encoded as yamlEncode(settings)
29
- show encoded
30
-
31
- remember parsed as yamlDecode(encoded)
32
- show app of parsed
33
- remember limits as limits of parsed
34
- show requests of limits
35
-
36
- load env file ".env"
37
- show env("APP_ENV")
38
-
39
- // JSON round-trip stays convenient too
40
- remember backup as jsonEncode(settings)
41
- show jsonDecode(backup)
42
-
43
- // Clean up after ourselves
44
- deleteFile("example-output/greeting.txt")
45
- deleteFile("example-output/log.txt")
46
- deleteFolder("example-output")
47
- show "cleanup done"
6
+ show fileExists(filename)
@@ -0,0 +1,12 @@
1
+ // PlainScript 1.0.3: file and path operations.
2
+
3
+ remember report as readFile("README.md")
4
+ show length(report)
5
+
6
+ remember outputPath as joinPath("tmp", "report.txt")
7
+ writeFile(outputPath, "PlainScript report")
8
+ appendFile(outputPath, "\nready")
9
+ show fileExists(outputPath)
10
+
11
+ remember parts as split(outputPath, "/")
12
+ show parts