plainscript-lang 1.0.3-beta → 1.0.35

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 (77) hide show
  1. package/README.md +126 -120
  2. package/compiler/bundler.js +83 -12
  3. package/compiler/cli.js +62 -11
  4. package/compiler/dependency-detector.js +17 -2
  5. package/compiler/generator.js +699 -63
  6. package/compiler/lexer.js +2 -0
  7. package/compiler/parser.js +450 -30
  8. package/compiler/sourcemap.js +142 -0
  9. package/compiler/version.js +1 -1
  10. package/docs/CAPABILITY_GAP_AUDIT.md +24 -16
  11. package/docs/PLAINSCRIPT-SPEC.md +175 -41
  12. package/docs/index.html +62 -34
  13. package/docs/logo-pln.jpg +0 -0
  14. package/docs/visualization-example.svg +32 -0
  15. package/docs/website/script.js +297 -19
  16. package/docs/website/style.css +357 -47
  17. package/examples/ai-providers.pln +1 -1
  18. package/examples/arrays.pln +1 -1
  19. package/examples/async-errors.pln +1 -1
  20. package/examples/auth-api.pln +1 -1
  21. package/examples/auth-sessions.pln +1 -1
  22. package/examples/basics.pln +1 -1
  23. package/examples/bots.pln +1 -1
  24. package/examples/cache-and-jobs.pln +1 -1
  25. package/examples/cache-schedule.pln +1 -1
  26. package/examples/collections.pln +1 -1
  27. package/examples/concurrency.pln +1 -1
  28. package/examples/conditions.pln +1 -1
  29. package/examples/database.pln +1 -1
  30. package/examples/day2.pln +1 -1
  31. package/examples/day3.pln +1 -1
  32. package/examples/deployment.pln +1 -1
  33. package/examples/email-send.pln +1 -1
  34. package/examples/error-handling.pln +1 -1
  35. package/examples/expressions.pln +1 -1
  36. package/examples/file-uploads.pln +1 -1
  37. package/examples/files-and-config.pln +1 -1
  38. package/examples/files.pln +1 -1
  39. package/examples/football-backend/app.pln +1 -1
  40. package/examples/functions.pln +1 -1
  41. package/examples/hello.pln +1 -1
  42. package/examples/http-client.pln +1 -1
  43. package/examples/http.pln +1 -1
  44. package/examples/id-verification/app.pln +1 -1
  45. package/examples/json.pln +1 -1
  46. package/examples/loops.pln +1 -1
  47. package/examples/modules/app.pln +1 -1
  48. package/examples/modules/main.pln +1 -1
  49. package/examples/modules/math.pln +1 -1
  50. package/examples/mongo.pln +33 -0
  51. package/examples/objects.pln +1 -1
  52. package/examples/ocr.pln +1 -1
  53. package/examples/packages.pln +1 -1
  54. package/examples/record-kinds.pln +1 -1
  55. package/examples/records.pln +1 -1
  56. package/examples/rest-api-fetch.pln +1 -1
  57. package/examples/rest-api.pln +1 -1
  58. package/examples/scheduled-tasks.pln +1 -1
  59. package/examples/search-and-filter.pln +1 -1
  60. package/examples/server.pln +1 -1
  61. package/examples/sessions-and-cookies.pln +1 -1
  62. package/examples/sqlite.pln +1 -1
  63. package/examples/start.pln +1 -1
  64. package/examples/stdlib.pln +1 -1
  65. package/examples/string-verbs.pln +16 -0
  66. package/examples/telegram-ai-bot.pln +1 -1
  67. package/examples/telegram-bot.pln +1 -1
  68. package/examples/testing.pln +1 -1
  69. package/examples/visualization.pln +12 -0
  70. package/examples/web-api.pln +1 -1
  71. package/examples/web-app.pln +1 -1
  72. package/examples/websocket-server.pln +1 -1
  73. package/examples/websocket.pln +1 -1
  74. package/examples/whatsapp-bot/pairing.pln +24 -2
  75. package/examples/whatsapp-bot/qr.pln +18 -2
  76. package/package.json +4 -2
  77. package/docs/logo.jpg +0 -0
@@ -0,0 +1,142 @@
1
+ // SourceMap: V3 Source Map generator for PlainScript compiler.
2
+ // Zero external dependencies — implements VLQ Base64 encoding.
3
+
4
+ const BASE64_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
5
+
6
+ function encodeVlq(value) {
7
+ let vlq = value < 0 ? ((-value) << 1) | 1 : (value << 1);
8
+ let encoded = '';
9
+ do {
10
+ let digit = vlq & 31;
11
+ vlq >>>= 5;
12
+ if (vlq > 0) {
13
+ digit |= 32;
14
+ }
15
+ encoded += BASE64_CHARS[digit];
16
+ } while (vlq > 0);
17
+ return encoded;
18
+ }
19
+
20
+ function decodeVlq(str, state = { index: 0 }) {
21
+ let result = 0;
22
+ let shift = 0;
23
+ let continuation = true;
24
+ while (continuation && state.index < str.length) {
25
+ const char = str[state.index++];
26
+ const digit = BASE64_CHARS.indexOf(char);
27
+ if (digit === -1) throw new Error(`Invalid Base64 character: ${char}`);
28
+ continuation = (digit & 32) !== 0;
29
+ result += (digit & 31) << shift;
30
+ shift += 5;
31
+ }
32
+ const isNegative = (result & 1) === 1;
33
+ const value = result >> 1;
34
+ return isNegative ? -value : value;
35
+ }
36
+
37
+ class SourceMapGenerator {
38
+ constructor(options = {}) {
39
+ this.file = options.file || '';
40
+ this.sourceRoot = options.sourceRoot || '';
41
+ this.sources = [];
42
+ this.sourcesContent = [];
43
+ this.mappings = [];
44
+ }
45
+
46
+ addSource(sourcePath, content = null) {
47
+ let idx = this.sources.indexOf(sourcePath);
48
+ if (idx === -1) {
49
+ idx = this.sources.length;
50
+ this.sources.push(sourcePath);
51
+ this.sourcesContent.push(content);
52
+ } else if (content !== null && this.sourcesContent[idx] === null) {
53
+ this.sourcesContent[idx] = content;
54
+ }
55
+ return idx;
56
+ }
57
+
58
+ addMapping({ generated, original, source }) {
59
+ if (!generated || generated.line == null || generated.column == null) return;
60
+ if (!original || original.line == null || original.column == null) return;
61
+
62
+ const sourceIdx = source ? this.addSource(source) : 0;
63
+ this.mappings.push({
64
+ generatedLine: generated.line,
65
+ generatedColumn: generated.column,
66
+ originalLine: original.line,
67
+ originalColumn: original.column,
68
+ sourceIdx,
69
+ });
70
+ }
71
+
72
+ toJSON() {
73
+ // Sort mappings by generated line, then generated column
74
+ const sorted = [...this.mappings].sort((a, b) => {
75
+ if (a.generatedLine !== b.generatedLine) return a.generatedLine - b.generatedLine;
76
+ return a.generatedColumn - b.generatedColumn;
77
+ });
78
+
79
+ let mappingsStr = '';
80
+ let prevGenLine = 1;
81
+ let prevGenCol = 0;
82
+ let prevOrigLine = 0;
83
+ let prevOrigCol = 0;
84
+ let prevSourceIdx = 0;
85
+
86
+ for (const m of sorted) {
87
+ while (prevGenLine < m.generatedLine) {
88
+ mappingsStr += ';';
89
+ prevGenLine++;
90
+ prevGenCol = 0;
91
+ }
92
+
93
+ if (mappingsStr.length > 0 && !mappingsStr.endsWith(';')) {
94
+ mappingsStr += ',';
95
+ }
96
+
97
+ const genColDiff = m.generatedColumn - prevGenCol;
98
+ const sourceIdxDiff = m.sourceIdx - prevSourceIdx;
99
+ const origLineDiff = (m.originalLine - 1) - prevOrigLine;
100
+ const origColDiff = (m.originalColumn - 1) - prevOrigCol;
101
+
102
+ mappingsStr += encodeVlq(genColDiff);
103
+ mappingsStr += encodeVlq(sourceIdxDiff);
104
+ mappingsStr += encodeVlq(origLineDiff);
105
+ mappingsStr += encodeVlq(origColDiff);
106
+
107
+ prevGenCol = m.generatedColumn;
108
+ prevSourceIdx = m.sourceIdx;
109
+ prevOrigLine = m.originalLine - 1;
110
+ prevOrigCol = m.originalColumn - 1;
111
+ }
112
+
113
+ const mapObj = {
114
+ version: 3,
115
+ file: this.file,
116
+ sources: this.sources,
117
+ mappings: mappingsStr,
118
+ };
119
+
120
+ if (this.sourcesContent.some(c => c !== null)) {
121
+ mapObj.sourcesContent = this.sourcesContent;
122
+ }
123
+
124
+ return mapObj;
125
+ }
126
+
127
+ toString() {
128
+ return JSON.stringify(this.toJSON());
129
+ }
130
+
131
+ toInlineDataUrl() {
132
+ const json = this.toString();
133
+ const base64 = Buffer.from(json, 'utf8').toString('base64');
134
+ return `//# sourceMappingURL=data:application/json;charset=utf-8;base64,${base64}`;
135
+ }
136
+ }
137
+
138
+ module.exports = {
139
+ SourceMapGenerator,
140
+ encodeVlq,
141
+ decodeVlq,
142
+ };
@@ -1,6 +1,6 @@
1
1
  // Single source of truth for the compiler version.
2
2
  // Consumed by cli.js help/version output.
3
3
 
4
- const VERSION = '1.0.3-beta';
4
+ const VERSION = '1.0.35';
5
5
 
6
6
  module.exports = { VERSION };
@@ -1,10 +1,9 @@
1
- # PlainScript 1.0.3-beta capability audit
1
+ # PlainScript 1.0.35 Capability Audit
2
2
 
3
- This audit is intentionally grounded in the implementation, not in old
4
- examples. The parser and generator are the authority. A capability is listed
5
- here only when a source program can be validated by `plainscript check`.
3
+ This audit is based on what the compiler actually supports right now.
4
+ If `plainscript check` validates it, it's listed here.
6
5
 
7
- ## Core language
6
+ ## Core Language
8
7
 
9
8
  | Capability | Status | Current source form |
10
9
  | --- | --- | --- |
@@ -19,9 +18,10 @@ here only when a source program can be validated by `plainscript check`.
19
18
  | For and while loops | Implemented | `for each ... done`, `while ... done` |
20
19
  | Match and switch | Implemented | `match value against ... done` |
21
20
  | Loop control | Implemented | `break`, `continue` |
21
+ | String verbs | Implemented | `lowercase`, `uppercase`, `split`, `join`, `trim`, `capitalize words` |
22
22
  | Classes and `new` | Implemented | JavaScript-compatible class forms |
23
23
 
24
- ## Modules and runtime
24
+ ## Modules and Runtime
25
25
 
26
26
  | Capability | Status | Notes |
27
27
  | --- | --- | --- |
@@ -36,7 +36,7 @@ here only when a source program can be validated by `plainscript check`.
36
36
  | Errors and retries | Implemented | `try`, `recover`, `finally`, `retry` |
37
37
  | Native tests | Implemented | `test` and `check` assertions |
38
38
 
39
- ## Web and services
39
+ ## Web and Services
40
40
 
41
41
  | Capability | Status | Current source form |
42
42
  | --- | --- | --- |
@@ -52,18 +52,23 @@ here only when a source program can be validated by `plainscript check`.
52
52
  | SQLite | Implemented | native and WebAssembly drivers |
53
53
  | PostgreSQL generation | Implemented | `postgres connection` |
54
54
  | SQL parameter binding | Implemented | `{variable}` placeholders |
55
+ | MongoDB | Implemented | `mongo connection`, insert, select, update, delete |
56
+ | MongoDB insert | Implemented | `insert into ... done` |
57
+ | MongoDB select | Implemented | `select from ... done` |
58
+ | MongoDB update | Implemented | `update ... set ... done` |
59
+ | MongoDB delete | Implemented | `delete from ... done` |
55
60
  | Email | Implemented | `mail transport`, `send mail` |
56
61
  | Schedules and jobs | Implemented | `every`, `schedule`, `run background` |
57
62
  | WebSockets | Implemented | `websocket server` |
58
63
  | Redis/in-memory cache | Implemented | `cache`, `cacheGet`, `cacheSet` |
59
64
  | Telegram bots | Implemented | `bot`, message/callback handlers |
60
65
  | AI providers | Implemented | `chat`, `chatWith`, `embedText`, provider presets |
61
- | WhatsApp bots | Implemented | `whatsapp bot` |
66
+ | WhatsApp bots | Implemented | `whatsapp bot` (pairing/QR, message types, media download, custom Baileys) |
62
67
  | OCR | Implemented | `ocr path of file as text` |
63
68
 
64
- ## Canonical examples
69
+ ## Canonical Examples
65
70
 
66
- The maintained examples are the executable capability matrix:
71
+ Here are the example files that exercise each capability:
67
72
 
68
73
  ```text
69
74
  examples/basics.pln
@@ -92,11 +97,14 @@ examples/id-verification/
92
97
  examples/whatsapp-bot/
93
98
  ```
94
99
 
95
- Run `find examples -name '*.pln' -exec node compiler/cli.js check {} \;`
96
- before changing the language reference.
100
+ Run this to make sure everything still compiles:
97
101
 
98
- ## Version boundary
102
+ ```bash
103
+ find examples -name '*.pln' -exec node compiler/cli.js check {} \;
104
+ ```
105
+
106
+ ## Version Info
99
107
 
100
- The repository release label is `1.0.3-beta`. This label identifies the
101
- compiler, package metadata, website, and editor tooling. It does not change
102
- third-party dependency versions.
108
+ The release label for this repo is `1.0.35`. It covers the compiler,
109
+ package metadata, website, and editor tooling. Third-party dependency
110
+ versions are not tied to this label.
@@ -1,17 +1,17 @@
1
- # PlainScript 1.0.3-beta language specification
1
+ # PlainScript 1.0.35 language specification
2
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
3
+ This reference covers the syntax implemented by `compiler/lexer.js` and
4
+ `compiler/parser.js`. The runtime it generates lives in
5
+ `compiler/generator.js`. Every example here is checked against the
6
6
  repository's maintained example set.
7
7
 
8
8
  ## Design
9
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.
10
+ PlainScript is a line-oriented, intent-oriented language made for Node.js.
11
+ Source files use `.pln`. Blocks end with `done` unless the syntax says
12
+ `together`. Whitespace does not matter.
13
13
 
14
- The canonical declaration forms are:
14
+ The basic declaration forms are:
15
15
 
16
16
  ```plainscript
17
17
  remember name as "Ada"
@@ -21,13 +21,13 @@ show name
21
21
  ```
22
22
 
23
23
  Comments begin with `//`. Double-quoted strings support escapes. Backtick
24
- strings preserve content and support `${expression}` interpolation.
24
+ strings keep their content as-is and support `${expression}` interpolation.
25
25
 
26
26
  ## Values and expressions
27
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.
28
+ PlainScript has strings, template strings, numbers, booleans, `null`,
29
+ `undefined`, BigInt, arrays, objects, identifiers, function calls, member
30
+ access, optional member access, and indexed access.
31
31
 
32
32
  ```plainscript
33
33
  remember names as ["Ada", "Grace"]
@@ -36,7 +36,7 @@ show names[0]
36
36
  show user?.name
37
37
  ```
38
38
 
39
- English collection expressions:
39
+ English-style collection expressions:
40
40
 
41
41
  ```plainscript
42
42
  remember items as list with "one", "two", "three"
@@ -47,10 +47,10 @@ show item one from items
47
47
  show items at position 1
48
48
  ```
49
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.
50
+ Arithmetic uses `+`, `-`, `*`, `/`, `%`, and `**`, with normal
51
+ precedence. Word forms `plus`, `minus`, `times`, and `divided by` also work.
52
+ `??` plus unary `-`, `wait for`, `typeof`, `void`, and `delete` are
53
+ supported.
54
54
 
55
55
  ## Conditions
56
56
 
@@ -82,6 +82,8 @@ Use `and`, `or`, and `not` to combine conditions. Inline conditionals use
82
82
 
83
83
  ## Functions
84
84
 
85
+ Write a function with `make` and return a value with `give`:
86
+
85
87
  ```plainscript
86
88
  make add(a, b)
87
89
  give a + b
@@ -98,8 +100,8 @@ make greet(name as "friend")
98
100
  done
99
101
  ```
100
102
 
101
- Aliases `define`, `function`, `return`, and `give back` are implemented. The
102
- readable declaration form is:
103
+ Aliases like `define`, `function`, `return`, and `give back` also work. Use
104
+ `make` and `give` for the readable form:
103
105
 
104
106
  ```plainscript
105
107
  make add(a, b)
@@ -107,8 +109,8 @@ make add(a, b)
107
109
  done
108
110
  ```
109
111
 
110
- `yield` creates a generator function. Functions may use `wait for` and other
111
- async operations.
112
+ `yield` turns a function into a generator. Functions can use `wait for` and
113
+ other async operations.
112
114
 
113
115
  ## Control flow
114
116
 
@@ -127,8 +129,8 @@ done
127
129
  ```
128
130
 
129
131
  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
+ case arrows and `otherwise`. `switch value against` works the same way and
133
+ is just another way to write it.
132
134
 
133
135
  ## Record kinds
134
136
 
@@ -141,8 +143,9 @@ done
141
143
  remember player as create a Player with name "Ada" and goals 4
142
144
  ```
143
145
 
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
+ `define a kind called` makes a new record kind. Fields use default
147
+ expressions. `create a Kind with field value and field value` builds an
148
+ instance.
146
149
 
147
150
  ## Modules and packages
148
151
 
@@ -153,7 +156,7 @@ export circleArea
153
156
  use express
154
157
  ```
155
158
 
156
- Imports are bundled in dependency order. `use` declares an npm package.
159
+ Imports get bundled in dependency order. `use` declares an npm package.
157
160
 
158
161
  ## Web server syntax
159
162
 
@@ -179,7 +182,7 @@ Methods are `get`, `post`, `put`, `patch`, and `delete`. Request values use
179
182
  `body of request`, `param("id")`, `query("name")`, `header("x-token")`,
180
183
  `upload("file")`, and `uploads("file")`.
181
184
 
182
- Server capabilities include:
185
+ The server also supports:
183
186
 
184
187
  ```plainscript
185
188
  enable sessions "secret"
@@ -208,8 +211,8 @@ done
208
211
  ```
209
212
 
210
213
  SQL blocks are closed by `done`. `{variable}` placeholders are bound safely.
211
- `transaction ... done` groups writes. `postgres connection` selects
212
- PostgreSQL generation.
214
+ `transaction ... done` groups writes. `postgres connection` generates
215
+ PostgreSQL code instead.
213
216
 
214
217
  HTTP client expressions:
215
218
 
@@ -234,14 +237,14 @@ done
234
237
  ```
235
238
 
236
239
  Concurrency helpers are `allOf`, `anyOf`, `settledOf`, and `withTimeout`.
237
- Recurring blocks are `every 5 minutes ... done` and
240
+ Recurring blocks use `every 5 minutes ... done` and
238
241
  `schedule "0 * * * *" ... done`.
239
242
 
240
243
  ## AI providers
241
244
 
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
+ `chat(model, messages, options)` and `embedText(model, text, options)` talk
246
+ to an OpenAI-compatible API. Provider presets pick safe defaults for the
247
+ endpoint and the environment variable:
245
248
 
246
249
  | Provider | API key | Default base |
247
250
  | --- | --- | --- |
@@ -264,10 +267,9 @@ show answer
264
267
  ```
265
268
 
266
269
  `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.
270
+ are optional. Custom providers can supply a provider name plus `base` and
271
+ `key`; the runtime falls back to `PROVIDER_API_KEY` and `PROVIDER_BASE_URL`.
272
+ These calls work in ordinary programs, routes, jobs, and messaging handlers.
271
273
 
272
274
  ## WebSockets, cache, bots, and OCR
273
275
 
@@ -297,17 +299,149 @@ start telegram bot
297
299
  ```
298
300
 
299
301
  Inside a Telegram handler, `message`, `text`, `args`, `matches`, `chat`,
300
- `chatId`, and callback `data` are update context values. Fixed replies use
302
+ `chatId`, and callback `data` hold the update context. Fixed replies use
301
303
  `reply "text"`; provider-backed replies can use `chatWith` before `reply`.
302
- `telegramCall(method, params)` invokes any Telegram Bot API method.
304
+ `telegramCall(method, params)` calls any Telegram Bot API method.
305
+
306
+ ### WhatsApp
307
+
308
+ WhatsApp bots are declared with a `whatsapp bot ... done` block. The block
309
+ accepts the following clauses:
310
+
311
+ | Clause | Purpose |
312
+ |--------|---------|
313
+ | `auth "<folder>"` | Path where session credentials persist across restarts. |
314
+ | `use baileys "<pkg>"` | Optional. Override the Baileys package (default: `@qwerty-xcv/baileys`). |
315
+ | `login qr` | Authenticate by scanning a QR code in the terminal. |
316
+ | `login pairing "<phone>"` | Authenticate by entering a phone number (digits only, no `+`). The argument may also be an expression such as `env("WHATSAPP_PHONE")`. |
317
+ | `on message ... done` | Handler that fires for every incoming message. |
318
+
319
+ Inside `on message` the incoming record is bound to `message`. Useful fields
320
+ include `message.text`, `message.type`, `message.mtype`, `message.caption`,
321
+ `message.buttonId`, `message.chat`, `message.sender`, `message.name`,
322
+ `message.id`, `message.time`, and `message.isGroup`.
323
+
324
+ **Pairing login example:**
325
+
326
+ ```plainscript
327
+ whatsapp bot
328
+ auth "plain-script-whatsapp"
329
+ use baileys "@qwerty-xcv/baileys"
330
+ login pairing "2348012345678"
331
+ on message
332
+ if message.text is "/start"
333
+ reply "Welcome!"
334
+ done
335
+ if message.text is "/help"
336
+ reply "Available commands:\n/start\n/help"
337
+ done
338
+ done
339
+ done
340
+ ```
303
341
 
304
- WhatsApp uses `whatsapp bot ... done`, with `auth`, `login qr`, `login
305
- pairing`, and `on message` clauses. OCR uses:
342
+ **QR login example:**
343
+
344
+ ```plainscript
345
+ whatsapp bot
346
+ auth "plain-script-whatsapp"
347
+ login qr
348
+ on message
349
+ if message.text is "/start"
350
+ reply "Welcome"
351
+ done
352
+ if message.type is "image"
353
+ download "media/photo.jpg"
354
+ reply "Saved your photo!"
355
+ done
356
+ if message.type is "button"
357
+ reply "You chose: " + message.buttonId
358
+ done
359
+ done
360
+ done
361
+ ```
362
+
363
+ #### Sending different message types
364
+
365
+ Inside `on message` you can branch on `message.type` to handle text, images,
366
+ documents, buttons, lists, and more. The following helpers are available:
367
+
368
+ | Statement | Effect |
369
+ |-----------|--------|
370
+ | `reply <value>` | Send a plain-text reply. |
371
+ | `reply <value> with buttons ... done` | Send interactive buttons. |
372
+ | `download "<path>"` | Save incoming media (image, audio, document …) to disk. |
373
+ | `log message` | Print the full message record for debugging. |
374
+
375
+ `message.type` values include `"text"`, `"image"`, `"video"`, `"audio"`,
376
+ `"document"`, `"sticker"`, `"button"`, `"list"`, `"template-button"`,
377
+ `"reaction"`, `"contact"`, `"contacts"`, `"location"`, `"live-location"`,
378
+ `"poll"`, `"group-invite"`, and `"other"`.
379
+
380
+ **Full example — media, buttons, and list replies:**
381
+
382
+ ```plainscript
383
+ whatsapp bot
384
+ auth "plain-script-whatsapp"
385
+ use baileys "@qwerty-xcv/baileys"
386
+ login pairing env("WHATSAPP_PHONE")
387
+ on message
388
+ log message
389
+ if message.text is "/menu"
390
+ reply "Choose a topic" with buttons
391
+ "Hours" -> "hours"
392
+ "Pricing" -> "pricing"
393
+ "Human" -> "human"
394
+ done
395
+ done
396
+ if message.type is "image"
397
+ download "downloads/photo.jpg"
398
+ reply "Got your picture. We saved it for the team."
399
+ done
400
+ if message.type is "document"
401
+ download "downloads/file.bin"
402
+ reply "We received your document."
403
+ done
404
+ if message.type is "button"
405
+ reply "You chose: " + message.buttonId
406
+ done
407
+ if message.type is "list"
408
+ reply "You picked: " + message.buttonId
409
+ done
410
+ done
411
+ done
412
+ ```
413
+
414
+ OCR uses:
306
415
 
307
416
  ```plainscript
308
417
  ocr path of file as text
309
418
  ```
310
419
 
420
+ ## Images and visualizations
421
+
422
+ The standard library creates dependency-free SVG images:
423
+
424
+ ```plainscript
425
+ remember labels as ["Jan", "Feb", "Mar"]
426
+ remember values as [12, 18, 27]
427
+ remember chart as barChart("Monthly signups", labels, values)
428
+ saveImage("signups.svg", chart)
429
+ ```
430
+
431
+ The available helpers are:
432
+
433
+ | Function | Result |
434
+ | --- | --- |
435
+ | `svgImage(width, height, markup, options)` | An SVG image string containing custom markup. |
436
+ | `barChart(title, labels, values, options)` | An SVG bar chart. |
437
+ | `lineChart(title, labels, values, options)` | An SVG line chart. |
438
+ | `saveImage(path, image)` | Writes an SVG image string to disk and returns the path. |
439
+ | `imageDataUri(image)` | Converts an SVG image string to a browser data URI. |
440
+
441
+ Chart options may include `width`, `height`, `background`, `foreground`,
442
+ `grid`, `accent`, and `muted`. Image values are strings, so they can also be
443
+ returned from a route or inserted into HTML.
444
+
311
445
  ## Native tests
312
446
 
313
447
  ```plainscript