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.
- package/README.md +126 -120
- package/compiler/bundler.js +83 -12
- package/compiler/cli.js +62 -11
- package/compiler/dependency-detector.js +17 -2
- package/compiler/generator.js +699 -63
- package/compiler/lexer.js +2 -0
- package/compiler/parser.js +450 -30
- package/compiler/sourcemap.js +142 -0
- package/compiler/version.js +1 -1
- package/docs/CAPABILITY_GAP_AUDIT.md +24 -16
- package/docs/PLAINSCRIPT-SPEC.md +175 -41
- package/docs/index.html +62 -34
- package/docs/logo-pln.jpg +0 -0
- package/docs/visualization-example.svg +32 -0
- package/docs/website/script.js +297 -19
- package/docs/website/style.css +357 -47
- package/examples/ai-providers.pln +1 -1
- package/examples/arrays.pln +1 -1
- package/examples/async-errors.pln +1 -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/cache-and-jobs.pln +1 -1
- package/examples/cache-schedule.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 +1 -1
- 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/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 +33 -0
- 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 +16 -0
- package/examples/telegram-ai-bot.pln +1 -1
- package/examples/telegram-bot.pln +1 -1
- package/examples/testing.pln +1 -1
- package/examples/visualization.pln +12 -0
- 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 +24 -2
- package/examples/whatsapp-bot/qr.pln +18 -2
- package/package.json +4 -2
- 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
|
+
};
|
package/compiler/version.js
CHANGED
|
@@ -1,10 +1,9 @@
|
|
|
1
|
-
# PlainScript 1.0.
|
|
1
|
+
# PlainScript 1.0.35 Capability Audit
|
|
2
2
|
|
|
3
|
-
This audit is
|
|
4
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
69
|
+
## Canonical Examples
|
|
65
70
|
|
|
66
|
-
|
|
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
|
|
96
|
-
before changing the language reference.
|
|
100
|
+
Run this to make sure everything still compiles:
|
|
97
101
|
|
|
98
|
-
|
|
102
|
+
```bash
|
|
103
|
+
find examples -name '*.pln' -exec node compiler/cli.js check {} \;
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## Version Info
|
|
99
107
|
|
|
100
|
-
The
|
|
101
|
-
|
|
102
|
-
|
|
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.
|
package/docs/PLAINSCRIPT-SPEC.md
CHANGED
|
@@ -1,17 +1,17 @@
|
|
|
1
|
-
# PlainScript 1.0.
|
|
1
|
+
# PlainScript 1.0.35 language specification
|
|
2
2
|
|
|
3
|
-
This reference
|
|
4
|
-
`compiler/parser.js`. The
|
|
5
|
-
`compiler/generator.js`.
|
|
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.
|
|
11
|
-
files use `.pln`. Blocks
|
|
12
|
-
`together`. Whitespace
|
|
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
|
|
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
|
|
24
|
+
strings keep their content as-is and support `${expression}` interpolation.
|
|
25
25
|
|
|
26
26
|
## Values and expressions
|
|
27
27
|
|
|
28
|
-
|
|
29
|
-
`undefined`, BigInt, arrays, objects, identifiers, calls, member
|
|
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
|
|
51
|
-
precedence. Word forms `plus`, `minus`, `times`, and `divided by`
|
|
52
|
-
|
|
53
|
-
|
|
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`
|
|
102
|
-
readable
|
|
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`
|
|
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`
|
|
131
|
-
|
|
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`
|
|
145
|
-
`create a Kind with field value and field value`
|
|
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
|
|
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
|
-
|
|
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`
|
|
212
|
-
PostgreSQL
|
|
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
|
|
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)`
|
|
243
|
-
OpenAI-compatible API. Provider presets
|
|
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
|
|
268
|
-
`
|
|
269
|
-
|
|
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`
|
|
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)`
|
|
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
|
-
|
|
305
|
-
|
|
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
|