plainscript-lang 0.1.7-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.
- package/LICENSE +21 -0
- package/README.md +815 -0
- package/compiler/bundler.js +86 -0
- package/compiler/cli.js +843 -0
- package/compiler/dependency-detector.js +173 -0
- package/compiler/formatter.js +170 -0
- package/compiler/generator.js +2032 -0
- package/compiler/lexer.js +413 -0
- package/compiler/parser.js +2077 -0
- package/compiler/version.js +6 -0
- package/docs/PLINJS_SPEC.md +1051 -0
- package/docs/index.html +2287 -0
- package/docs/logo.jpg +0 -0
- package/docs/website/index.html +1500 -0
- package/docs/website/script.js +197 -0
- package/docs/website/style.css +1117 -0
- package/examples/arrays.pln +13 -0
- package/examples/cache-and-jobs.pln +29 -0
- package/examples/database.pln +41 -0
- package/examples/day2.pln +7 -0
- package/examples/day3.pln +11 -0
- package/examples/deployment.pln +12 -0
- package/examples/email-send.pln +22 -0
- package/examples/expressions.pln +40 -0
- package/examples/football-backend/app.pln +90 -0
- package/examples/hello.pln +3 -0
- package/examples/id-verification/app.pln +29 -0
- package/examples/id-verification/make-sample-id.js +123 -0
- package/examples/loops.pln +17 -0
- package/examples/objects.pln +12 -0
- package/examples/rest-api-fetch.pln +94 -0
- package/examples/rest-api.pln +68 -0
- package/examples/scheduled-tasks.pln +23 -0
- package/examples/server.pln +25 -0
- package/examples/start.pln +2 -0
- package/examples/stdlib.pln +41 -0
- package/examples/telegram-bot.pln +42 -0
- package/examples/web-app.pln +20 -0
- package/examples/websocket-server.pln +27 -0
- package/examples/whatsapp-bot/pairing.pln +17 -0
- package/examples/whatsapp-bot/qr.pln +8 -0
- package/package.json +47 -0
package/docs/index.html
ADDED
|
@@ -0,0 +1,2287 @@
|
|
|
1
|
+
<!DOCTYPE html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="UTF-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover">
|
|
6
|
+
|
|
7
|
+
<title>PlainScript — The programming language that reads like English</title>
|
|
8
|
+
<meta name="description" content="PlainScript is an Intent-Oriented Programming Language (IOPL). Write programs in near-English sentences and compile them to JavaScript..">
|
|
9
|
+
<meta name="keywords" content="PlainScript, IOPL, intent-oriented programming, programming language, JavaScript, PlainScript language, plainscript, beginner programming language">
|
|
10
|
+
<link rel="canonical" href="https://github.com/ayoistooslick/plain-code">
|
|
11
|
+
|
|
12
|
+
<meta property="og:type" content="website">
|
|
13
|
+
<meta property="og:url" content="https://ayoistooslick.github.io/plain-code/">
|
|
14
|
+
<meta property="og:title" content="PlainScript — The programming language that reads like English">
|
|
15
|
+
<meta property="og:description" content="Write programs in near-English sentences. PlainScript compiles to JavaScript..">
|
|
16
|
+
<meta property="og:image" content="https://ayoistooslick.github.io/plain-code/logo.jpg">
|
|
17
|
+
|
|
18
|
+
<meta name="twitter:card" content="summary_large_image">
|
|
19
|
+
<meta name="twitter:title" content="PlainScript — The programming language that reads like English">
|
|
20
|
+
<meta name="twitter:description" content="Write programs in near-English sentences. PlainScript compiles to JavaScript..">
|
|
21
|
+
<meta name="twitter:image" content="https://ayoistooslick.github.io/plain-code/logo.jpg">
|
|
22
|
+
|
|
23
|
+
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.2/css/all.min.css" crossorigin="anonymous" referrerpolicy="no-referrer">
|
|
24
|
+
<script src="https://cdn.tailwindcss.com"></script>
|
|
25
|
+
<link rel="stylesheet" href="website/style.css">
|
|
26
|
+
</head>
|
|
27
|
+
<body>
|
|
28
|
+
|
|
29
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
30
|
+
<!-- NAVIGATION -->
|
|
31
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
32
|
+
<nav class="site-nav" role="navigation" aria-label="Main navigation">
|
|
33
|
+
<div class="nav-inner">
|
|
34
|
+
<a class="nav-logo" href="#top">
|
|
35
|
+
<span class="logo-word">PlainScript</span>
|
|
36
|
+
<span class="logo-ver">v0.1.7</span>
|
|
37
|
+
</a>
|
|
38
|
+
|
|
39
|
+
<ul class="nav-links" role="list">
|
|
40
|
+
<li><a href="#introduction">Introduction</a></li>
|
|
41
|
+
<li><a href="#language">Language</a></li>
|
|
42
|
+
<li><a href="#web">Web</a></li>
|
|
43
|
+
<li><a href="#ocr">OCR</a></li>
|
|
44
|
+
<li><a href="#examples">Examples</a></li>
|
|
45
|
+
<li><a href="#backend-services">Backend Services</a></li>
|
|
46
|
+
<li><a href="#cli">CLI</a></li>
|
|
47
|
+
<li><a href="#security">Security</a></li>
|
|
48
|
+
</ul>
|
|
49
|
+
|
|
50
|
+
<div class="nav-actions">
|
|
51
|
+
<a class="nav-cta" href="https://github.com/ayoistooslick/plain-code" target="_blank" rel="noopener">
|
|
52
|
+
<i class="fa-brands fa-github"></i>
|
|
53
|
+
<span>GitHub</span>
|
|
54
|
+
</a>
|
|
55
|
+
<a class="nav-cta" href="https://www.npmjs.com/package/plainscript" target="_blank" rel="noopener">
|
|
56
|
+
<i class="fa-brands fa-npm"></i>
|
|
57
|
+
<span>npm</span>
|
|
58
|
+
</a>
|
|
59
|
+
<button class="nav-hamburger" id="nav-hamburger" aria-label="Toggle menu" aria-expanded="false">
|
|
60
|
+
<i class="fa-solid fa-bars"></i>
|
|
61
|
+
</button>
|
|
62
|
+
</div>
|
|
63
|
+
</div>
|
|
64
|
+
</nav>
|
|
65
|
+
|
|
66
|
+
<div class="mobile-menu" id="mobile-menu" role="dialog" aria-label="Mobile navigation">
|
|
67
|
+
<a href="#introduction">Introduction</a>
|
|
68
|
+
<a href="#quickstart">Quick Start</a>
|
|
69
|
+
<a href="#language">Language Reference</a>
|
|
70
|
+
<a href="#web">Web Development</a>
|
|
71
|
+
<a href="#http">HTTP</a>
|
|
72
|
+
<a href="#telegram">Telegram</a>
|
|
73
|
+
<a href="#whatsapp">WhatsApp</a>
|
|
74
|
+
<a href="#ocr">OCR</a>
|
|
75
|
+
<a href="#websocket">WebSocket</a>
|
|
76
|
+
<a href="#scheduling">Scheduling</a>
|
|
77
|
+
<a href="#email">Email</a>
|
|
78
|
+
<a href="#database">Database</a>
|
|
79
|
+
<a href="#examples">Examples</a>
|
|
80
|
+
<a href="#packages">Packages</a>
|
|
81
|
+
<a href="#cli">CLI Reference</a>
|
|
82
|
+
<a href="#backend-services">Backend Services</a>
|
|
83
|
+
<a href="#security">Security</a>
|
|
84
|
+
<a href="#roadmap">Roadmap</a>
|
|
85
|
+
<a href="https://github.com/ayoistooslick/plain-code" target="_blank" rel="noopener"><i class="fa-brands fa-github"></i> GitHub</a>
|
|
86
|
+
<a href="https://www.npmjs.com/package/plainscript" target="_blank" rel="noopener"><i class="fa-brands fa-npm"></i> npm</a>
|
|
87
|
+
</div>
|
|
88
|
+
|
|
89
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
90
|
+
<!-- HERO -->
|
|
91
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
92
|
+
<header class="hero" id="top">
|
|
93
|
+
<div class="container">
|
|
94
|
+
<div class="hero-grid">
|
|
95
|
+
|
|
96
|
+
<div class="hero-copy">
|
|
97
|
+
<div class="hero-badge">
|
|
98
|
+
<i class="fa-solid fa-bolt"></i>
|
|
99
|
+
v0.1.7 — production builds · dist output · local devDependency
|
|
100
|
+
</div>
|
|
101
|
+
<h1 class="hero-title">
|
|
102
|
+
The language<br>
|
|
103
|
+
that reads<br>
|
|
104
|
+
like <span class="accent">English.</span>
|
|
105
|
+
</h1>
|
|
106
|
+
<p class="hero-sub">
|
|
107
|
+
PlainScript is an Intent-Oriented Programming Language. Describe <em>what</em> you want in near-English sentences and PlainScript compiles it to JavaScript. No boilerplate, no ceremony.
|
|
108
|
+
</p>
|
|
109
|
+
<div class="hero-actions">
|
|
110
|
+
<a class="btn btn-primary" href="#quickstart">
|
|
111
|
+
<i class="fa-solid fa-rocket"></i>
|
|
112
|
+
Get Started
|
|
113
|
+
</a>
|
|
114
|
+
<a class="btn btn-outline" href="#language">
|
|
115
|
+
<i class="fa-solid fa-book"></i>
|
|
116
|
+
Language Reference
|
|
117
|
+
</a>
|
|
118
|
+
<a class="btn btn-outline" href="https://github.com/ayoistooslick/plain-code" target="_blank" rel="noopener">
|
|
119
|
+
<i class="fa-brands fa-github"></i>
|
|
120
|
+
GitHub
|
|
121
|
+
</a>
|
|
122
|
+
</div>
|
|
123
|
+
</div>
|
|
124
|
+
|
|
125
|
+
<div class="hero-code">
|
|
126
|
+
<div class="code-block">
|
|
127
|
+
<div class="code-block-header">
|
|
128
|
+
<div class="code-block-dots">
|
|
129
|
+
<span></span><span></span><span></span>
|
|
130
|
+
</div>
|
|
131
|
+
<span class="code-block-title">app.pln</span>
|
|
132
|
+
<button class="code-copy" aria-label="Copy code">
|
|
133
|
+
<i class="fa-regular fa-copy"></i> Copy
|
|
134
|
+
</button>
|
|
135
|
+
</div>
|
|
136
|
+
<pre><code><span class="kw">web app</span>
|
|
137
|
+
|
|
138
|
+
<span class="kw">route</span> <span class="str">"/"</span>
|
|
139
|
+
<span class="kw">reply json</span>
|
|
140
|
+
message <span class="kw">is</span> <span class="str">"Hello, World!"</span>
|
|
141
|
+
version <span class="kw">is</span> <span class="str">"1.0"</span>
|
|
142
|
+
<span class="kw">done</span>
|
|
143
|
+
<span class="kw">done</span>
|
|
144
|
+
|
|
145
|
+
<span class="kw">route</span> <span class="str">"/users/:id"</span>
|
|
146
|
+
<span class="kw">remember</span> id <span class="kw">as</span> request.params.id
|
|
147
|
+
<span class="kw">reply json</span>
|
|
148
|
+
user <span class="kw">is</span> id
|
|
149
|
+
status <span class="kw">is</span> <span class="str">"found"</span>
|
|
150
|
+
<span class="kw">done</span>
|
|
151
|
+
<span class="kw">done</span>
|
|
152
|
+
|
|
153
|
+
<span class="kw">start</span> <span class="num">3000</span></code></pre>
|
|
154
|
+
</div>
|
|
155
|
+
</div>
|
|
156
|
+
|
|
157
|
+
</div>
|
|
158
|
+
</div>
|
|
159
|
+
</header>
|
|
160
|
+
|
|
161
|
+
<div class="container">
|
|
162
|
+
<div class="stats-row">
|
|
163
|
+
<div class="stat-item">
|
|
164
|
+
<div class="stat-value">35<span class="unit">+</span></div>
|
|
165
|
+
<div class="stat-label">Keywords</div>
|
|
166
|
+
</div>
|
|
167
|
+
<div class="stat-item">
|
|
168
|
+
<div class="stat-value">625</div>
|
|
169
|
+
<div class="stat-label">Tests Passing</div>
|
|
170
|
+
</div>
|
|
171
|
+
<div class="stat-item">
|
|
172
|
+
<div class="stat-value">0</div>
|
|
173
|
+
<div class="stat-label">Config Files Needed</div>
|
|
174
|
+
</div>
|
|
175
|
+
<div class="stat-item">
|
|
176
|
+
<div class="stat-value">MIT</div>
|
|
177
|
+
<div class="stat-label">License</div>
|
|
178
|
+
</div>
|
|
179
|
+
</div>
|
|
180
|
+
</div>
|
|
181
|
+
|
|
182
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
183
|
+
<!-- INTRODUCTION -->
|
|
184
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
185
|
+
<section class="section" id="introduction">
|
|
186
|
+
<div class="container">
|
|
187
|
+
<div class="section-tag"><i class="fa-solid fa-lightbulb"></i> Introduction</div>
|
|
188
|
+
<h2 class="section-title">What is PlainScript?</h2>
|
|
189
|
+
<p class="section-lead">
|
|
190
|
+
PlainScript is an Intent-Oriented Programming Language (IOPL). It compiles <code>.pln</code> source files to JavaScript and runs them with Node.js. PlainScript’s design goal is to let developers describe <em>what</em> they want to happen in near-English sentences, while the compiler handles the JavaScript implementation details.
|
|
191
|
+
</p>
|
|
192
|
+
|
|
193
|
+
<div class="why-grid">
|
|
194
|
+
<div class="why-item">
|
|
195
|
+
<div class="why-num"><i class="fa-solid fa-pen-nib"></i></div>
|
|
196
|
+
<h3>Intent, not implementation</h3>
|
|
197
|
+
<p>Write <em>what</em> you want to happen, not <em>how</em> JavaScript should do it. The compiler bridges the gap, generating clean, readable JS output.</p>
|
|
198
|
+
</div>
|
|
199
|
+
<div class="why-item">
|
|
200
|
+
<div class="why-num"><i class="fa-solid fa-gauge-high"></i></div>
|
|
201
|
+
<h3>Zero configuration</h3>
|
|
202
|
+
<p>No webpack. No tsconfig. No babel. Drop a <code>.pln</code> file anywhere and run it. Zero configuration required.</p>
|
|
203
|
+
</div>
|
|
204
|
+
<div class="why-item">
|
|
205
|
+
<div class="why-num"><i class="fa-solid fa-ruler"></i></div>
|
|
206
|
+
<h3>One way to do everything</h3>
|
|
207
|
+
<p>No decision fatigue. PlainScript has exactly one way to declare a variable, one way to loop, one way to define a function. Less syntax to memorise, more time to build.</p>
|
|
208
|
+
</div>
|
|
209
|
+
<div class="why-item">
|
|
210
|
+
<div class="why-num"><i class="fa-solid fa-comment-dots"></i></div>
|
|
211
|
+
<h3>Errors that teach</h3>
|
|
212
|
+
<p>Every error message tells you what went wrong, which line, and — when possible — exactly what to type instead. The compiler is a tutor, not a gatekeeper.</p>
|
|
213
|
+
</div>
|
|
214
|
+
<div class="why-item">
|
|
215
|
+
<div class="why-num"><i class="fa-solid fa-puzzle-piece"></i></div>
|
|
216
|
+
<h3>npm-compatible</h3>
|
|
217
|
+
<p>Any npm package can be declared with <code>use</code> and installed with <code>plainscript add</code>. The entire Node.js ecosystem is one keyword away.</p>
|
|
218
|
+
</div>
|
|
219
|
+
<div class="why-item">
|
|
220
|
+
<div class="why-num"><i class="fa-solid fa-eye"></i></div>
|
|
221
|
+
<h3>Code that reads like docs</h3>
|
|
222
|
+
<p>PlainScript code doubles as documentation. Hand it to a non-programmer and they will understand it. That constraint makes your code better for everyone.</p>
|
|
223
|
+
</div>
|
|
224
|
+
</div>
|
|
225
|
+
|
|
226
|
+
<div class="callout callout-info" style="margin-top:2rem">
|
|
227
|
+
<i class="fa-solid fa-circle-info"></i>
|
|
228
|
+
<div class="callout-body">
|
|
229
|
+
<strong>What PlainScript is NOT</strong>
|
|
230
|
+
<p>PlainScript is <strong>not</strong> a natural-language prompt system. You cannot type free-form English and have it compile. Every construct in PlainScript is defined by explicit syntax and precise semantics. The language reads like English because it was designed that way — not because an AI is interpreting your intent at compile time. PlainScript is a real programming language with a deterministic compiler.</p>
|
|
231
|
+
</div>
|
|
232
|
+
</div>
|
|
233
|
+
</div>
|
|
234
|
+
</section>
|
|
235
|
+
|
|
236
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
237
|
+
<!-- INSTALLATION -->
|
|
238
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
239
|
+
<section class="section section--alt" id="installation">
|
|
240
|
+
<div class="container">
|
|
241
|
+
<div class="section-tag"><i class="fa-solid fa-download"></i> Installation</div>
|
|
242
|
+
<h2 class="section-title">Install PlainScript</h2>
|
|
243
|
+
<p class="section-lead">
|
|
244
|
+
PlainScript is a Node.js package. Install it globally and you’re ready to compile <code>.pln</code> files anywhere on your system.
|
|
245
|
+
</p>
|
|
246
|
+
|
|
247
|
+
<div class="install-strip">
|
|
248
|
+
<div class="install-strip-label">
|
|
249
|
+
<i class="fa-brands fa-npm"></i>
|
|
250
|
+
Install locally via npm
|
|
251
|
+
</div>
|
|
252
|
+
<div class="install-cmd">
|
|
253
|
+
<code>npm install --save-dev plainscript</code>
|
|
254
|
+
<button aria-label="Copy install command">
|
|
255
|
+
<i class="fa-regular fa-copy"></i> Copy
|
|
256
|
+
</button>
|
|
257
|
+
</div>
|
|
258
|
+
</div>
|
|
259
|
+
|
|
260
|
+
<div class="callout callout-info" style="margin-top:1.5rem">
|
|
261
|
+
<i class="fa-solid fa-circle-info"></i>
|
|
262
|
+
<div class="callout-body">
|
|
263
|
+
<strong>Requirements</strong>
|
|
264
|
+
<p>Node.js 16+ is required. PlainScript works on Windows, macOS, and Linux. No other dependencies are needed.</p>
|
|
265
|
+
</div>
|
|
266
|
+
</div>
|
|
267
|
+
</div>
|
|
268
|
+
</section>
|
|
269
|
+
|
|
270
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
271
|
+
<!-- QUICK START -->
|
|
272
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
273
|
+
<section class="section" id="quickstart">
|
|
274
|
+
<div class="container">
|
|
275
|
+
<div class="section-tag"><i class="fa-solid fa-rocket"></i> Quick Start</div>
|
|
276
|
+
<h2 class="section-title">Your first PlainScript program</h2>
|
|
277
|
+
<p class="section-lead">
|
|
278
|
+
PlainScript compiles <code>.pln</code> files to JavaScript and runs them with Node.js. No bundlers, no transpilers, no configuration required.
|
|
279
|
+
</p>
|
|
280
|
+
|
|
281
|
+
<h3 class="sub-heading"><i class="fa-solid fa-folder-plus"></i> Create a new project</h3>
|
|
282
|
+
|
|
283
|
+
<div class="code-block" style="margin-bottom:1.5rem">
|
|
284
|
+
<div class="code-block-header">
|
|
285
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
286
|
+
<span class="code-block-title">Terminal</span>
|
|
287
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
288
|
+
</div>
|
|
289
|
+
<pre><code><span class="prm">$</span> plainscript new myapp
|
|
290
|
+
<span class="prm">$</span> cd myapp
|
|
291
|
+
<span class="prm">$</span> plainscript install
|
|
292
|
+
<span class="prm">$</span> plainscript start</code></pre>
|
|
293
|
+
</div>
|
|
294
|
+
|
|
295
|
+
<h3 class="sub-heading"><i class="fa-solid fa-file-code"></i> Hello World</h3>
|
|
296
|
+
|
|
297
|
+
<div class="compare" style="margin-bottom:1.5rem">
|
|
298
|
+
<div class="code-block">
|
|
299
|
+
<div class="code-block-header">
|
|
300
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
301
|
+
<span class="code-block-title">hello.pln</span>
|
|
302
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
303
|
+
</div>
|
|
304
|
+
<pre><code><span class="kw">remember</span> name <span class="kw">as</span> <span class="str">"World"</span>
|
|
305
|
+
<span class="kw">show</span> <span class="str">"Hello, "</span> + name
|
|
306
|
+
|
|
307
|
+
<span class="kw">make</span> <span class="fn">greet</span>(person)
|
|
308
|
+
<span class="kw">show</span> <span class="str">"Nice to meet you, "</span> + person
|
|
309
|
+
<span class="kw">done</span>
|
|
310
|
+
|
|
311
|
+
<span class="fn">greet</span>(name)</code></pre>
|
|
312
|
+
</div>
|
|
313
|
+
<div class="code-block">
|
|
314
|
+
<div class="code-block-header">
|
|
315
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
316
|
+
<span class="code-block-title">Generated JavaScript</span>
|
|
317
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
318
|
+
</div>
|
|
319
|
+
<pre><code><span class="kw">let</span> name = <span class="str">"World"</span>;
|
|
320
|
+
console.<span class="fn">log</span>(<span class="str">"Hello, "</span> + name);
|
|
321
|
+
|
|
322
|
+
<span class="kw">function</span> <span class="fn">greet</span>(person) {
|
|
323
|
+
console.<span class="fn">log</span>(<span class="str">"Nice to meet you, "</span> + person);
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
<span class="fn">greet</span>(name);</code></pre>
|
|
327
|
+
</div>
|
|
328
|
+
</div>
|
|
329
|
+
|
|
330
|
+
<h3 class="sub-heading"><i class="fa-solid fa-terminal"></i> Run it</h3>
|
|
331
|
+
<div class="code-block" style="margin-bottom:1.5rem">
|
|
332
|
+
<div class="code-block-header">
|
|
333
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
334
|
+
<span class="code-block-title">Terminal</span>
|
|
335
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
336
|
+
</div>
|
|
337
|
+
<pre><code><span class="prm">$</span> plainscript run hello.pln
|
|
338
|
+
Hello, World!
|
|
339
|
+
Nice to meet you, World!</code></pre>
|
|
340
|
+
</div>
|
|
341
|
+
</div>
|
|
342
|
+
</section>
|
|
343
|
+
|
|
344
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
345
|
+
<!-- LANGUAGE REFERENCE -->
|
|
346
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
347
|
+
<section class="section section--alt" id="language">
|
|
348
|
+
<div class="container">
|
|
349
|
+
<div class="section-tag"><i class="fa-solid fa-book"></i> Language Reference</div>
|
|
350
|
+
<h2 class="section-title">Language Tour</h2>
|
|
351
|
+
<p class="section-lead">
|
|
352
|
+
A complete reference for every PlainScript construct. Every keyword compiles to a direct JavaScript equivalent — no magic, no hidden behaviour.
|
|
353
|
+
</p>
|
|
354
|
+
|
|
355
|
+
<!-- Variables -->
|
|
356
|
+
<h3 class="sub-heading"><i class="fa-solid fa-square-root-variable"></i> Variables</h3>
|
|
357
|
+
<p style="color:var(--muted);margin-bottom:.75rem">Declare with <code>remember … as</code>. Reassign with <code>becomes</code>.</p>
|
|
358
|
+
<div class="compare" style="margin-bottom:2rem">
|
|
359
|
+
<div class="code-block">
|
|
360
|
+
<div class="code-block-header">
|
|
361
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
362
|
+
<span class="code-block-title">PlainScript</span>
|
|
363
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
364
|
+
</div>
|
|
365
|
+
<pre><code><span class="kw">remember</span> name <span class="kw">as</span> <span class="str">"Ayokunle"</span>
|
|
366
|
+
<span class="kw">remember</span> score <span class="kw">as</span> <span class="num">100</span>
|
|
367
|
+
<span class="kw">remember</span> active <span class="kw">as</span> true
|
|
368
|
+
|
|
369
|
+
score <span class="kw">becomes</span> score + <span class="num">10</span></code></pre>
|
|
370
|
+
</div>
|
|
371
|
+
<div class="code-block">
|
|
372
|
+
<div class="code-block-header">
|
|
373
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
374
|
+
<span class="code-block-title">JavaScript</span>
|
|
375
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
376
|
+
</div>
|
|
377
|
+
<pre><code><span class="kw">let</span> name = <span class="str">"Ayokunle"</span>;
|
|
378
|
+
<span class="kw">let</span> score = <span class="num">100</span>;
|
|
379
|
+
<span class="kw">let</span> active = <span class="kw">true</span>;
|
|
380
|
+
|
|
381
|
+
score = score + <span class="num">10</span>;</code></pre>
|
|
382
|
+
</div>
|
|
383
|
+
</div>
|
|
384
|
+
|
|
385
|
+
<!-- Comparisons -->
|
|
386
|
+
<h3 class="sub-heading"><i class="fa-solid fa-scale-balanced"></i> Comparisons</h3>
|
|
387
|
+
<p style="color:var(--muted);margin-bottom:.75rem">PlainScript supports a full set of English comparison operators.</p>
|
|
388
|
+
<div class="table-wrap">
|
|
389
|
+
<table>
|
|
390
|
+
<thead>
|
|
391
|
+
<tr><th>PlainScript</th><th>JavaScript</th><th>Notes</th></tr>
|
|
392
|
+
</thead>
|
|
393
|
+
<tbody>
|
|
394
|
+
<tr><td><code>is</code> / <code>is equal to</code></td><td><code>===</code></td><td>Strict equality</td></tr>
|
|
395
|
+
<tr><td><code>is not</code></td><td><code>!==</code></td><td>Strict inequality</td></tr>
|
|
396
|
+
<tr><td><code>is greater than</code> / <code>is above</code></td><td><code>></code></td><td></td></tr>
|
|
397
|
+
<tr><td><code>is less than</code> / <code>is below</code></td><td><code><</code></td><td></td></tr>
|
|
398
|
+
<tr><td><code>is at least</code></td><td><code>>=</code></td><td></td></tr>
|
|
399
|
+
<tr><td><code>is at most</code></td><td><code><=</code></td><td></td></tr>
|
|
400
|
+
<tr><td><code>is empty</code></td><td><code>.length === 0</code></td><td>Arrays and strings</td></tr>
|
|
401
|
+
<tr><td><code>is not empty</code></td><td><code>.length > 0</code></td><td>Arrays and strings</td></tr>
|
|
402
|
+
<tr><td><code>contains "x"</code></td><td><code>.includes("x")</code></td><td></td></tr>
|
|
403
|
+
<tr><td><code>starts with "x"</code></td><td><code>.startsWith("x")</code></td><td></td></tr>
|
|
404
|
+
<tr><td><code>ends with "x"</code></td><td><code>.endsWith("x")</code></td><td></td></tr>
|
|
405
|
+
<tr><td><code>between A and B</code></td><td><code>>= A && <= B</code></td><td>Inclusive range</td></tr>
|
|
406
|
+
</tbody>
|
|
407
|
+
</table>
|
|
408
|
+
</div>
|
|
409
|
+
|
|
410
|
+
<!-- Conditions -->
|
|
411
|
+
<h3 class="sub-heading"><i class="fa-solid fa-code-branch"></i> Conditions</h3>
|
|
412
|
+
<div class="code-block" style="margin-bottom:2rem">
|
|
413
|
+
<div class="code-block-header">
|
|
414
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
415
|
+
<span class="code-block-title">conditions.pln</span>
|
|
416
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
417
|
+
</div>
|
|
418
|
+
<pre><code><span class="cmt">// if / otherwise</span>
|
|
419
|
+
<span class="kw">if</span> age <span class="kw">between</span> <span class="num">13</span> <span class="kw">and</span> <span class="num">19</span>
|
|
420
|
+
<span class="kw">show</span> <span class="str">"Teenager"</span>
|
|
421
|
+
<span class="kw">otherwise</span>
|
|
422
|
+
<span class="kw">show</span> <span class="str">"Not a teenager"</span>
|
|
423
|
+
<span class="kw">done</span>
|
|
424
|
+
|
|
425
|
+
<span class="kw">if</span> score <span class="kw">is at least</span> <span class="num">80</span>
|
|
426
|
+
<span class="kw">show</span> <span class="str">"Distinction"</span>
|
|
427
|
+
<span class="kw">done</span></code></pre>
|
|
428
|
+
</div>
|
|
429
|
+
|
|
430
|
+
<!-- Loops -->
|
|
431
|
+
<h3 class="sub-heading"><i class="fa-solid fa-rotate"></i> Loops</h3>
|
|
432
|
+
<div class="code-block" style="margin-bottom:2rem">
|
|
433
|
+
<div class="code-block-header">
|
|
434
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
435
|
+
<span class="code-block-title">loops.pln</span>
|
|
436
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
437
|
+
</div>
|
|
438
|
+
<pre><code><span class="cmt">// while loop</span>
|
|
439
|
+
<span class="kw">while</span> x <span class="kw">is above</span> <span class="num">0</span>
|
|
440
|
+
x <span class="kw">becomes</span> x + <span class="num">1</span>
|
|
441
|
+
<span class="kw">done</span>
|
|
442
|
+
|
|
443
|
+
<span class="cmt">// for each loop</span>
|
|
444
|
+
<span class="kw">for each</span> player <span class="kw">in</span> players
|
|
445
|
+
<span class="kw">show</span> player
|
|
446
|
+
<span class="kw">done</span>
|
|
447
|
+
|
|
448
|
+
<span class="cmt">// "for every" is an alias for "for each"</span>
|
|
449
|
+
<span class="kw">for every</span> item <span class="kw">in</span> basket
|
|
450
|
+
<span class="kw">show</span> item
|
|
451
|
+
<span class="kw">done</span></code></pre>
|
|
452
|
+
</div>
|
|
453
|
+
|
|
454
|
+
<!-- Functions -->
|
|
455
|
+
<h3 class="sub-heading"><i class="fa-solid fa-f"></i> Functions</h3>
|
|
456
|
+
<div class="compare" style="margin-bottom:2rem">
|
|
457
|
+
<div class="code-block">
|
|
458
|
+
<div class="code-block-header">
|
|
459
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
460
|
+
<span class="code-block-title">PlainScript</span>
|
|
461
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
462
|
+
</div>
|
|
463
|
+
<pre><code><span class="kw">make</span> <span class="fn">add</span>(a, b)
|
|
464
|
+
<span class="kw">give</span> a + b
|
|
465
|
+
<span class="kw">done</span>
|
|
466
|
+
|
|
467
|
+
<span class="kw">make</span> <span class="fn">greet</span>(name)
|
|
468
|
+
<span class="kw">show</span> <span class="str">"Hello, "</span> + name
|
|
469
|
+
<span class="kw">done</span>
|
|
470
|
+
|
|
471
|
+
<span class="kw">show</span> <span class="fn">add</span>(<span class="num">5</span>, <span class="num">7</span>) <span class="cmt">// 12</span>
|
|
472
|
+
<span class="fn">greet</span>(<span class="str">"World"</span>)</code></pre>
|
|
473
|
+
</div>
|
|
474
|
+
<div class="code-block">
|
|
475
|
+
<div class="code-block-header">
|
|
476
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
477
|
+
<span class="code-block-title">JavaScript</span>
|
|
478
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
479
|
+
</div>
|
|
480
|
+
<pre><code><span class="kw">function</span> <span class="fn">add</span>(a, b) {
|
|
481
|
+
<span class="kw">return</span> a + b;
|
|
482
|
+
}
|
|
483
|
+
|
|
484
|
+
<span class="kw">function</span> <span class="fn">greet</span>(name) {
|
|
485
|
+
console.<span class="fn">log</span>(<span class="str">"Hello, "</span> + name);
|
|
486
|
+
}
|
|
487
|
+
|
|
488
|
+
console.<span class="fn">log</span>(<span class="fn">add</span>(<span class="num">5</span>, <span class="num">7</span>)); <span class="cmt">// 12</span>
|
|
489
|
+
<span class="fn">greet</span>(<span class="str">"World"</span>);</code></pre>
|
|
490
|
+
</div>
|
|
491
|
+
</div>
|
|
492
|
+
|
|
493
|
+
<!-- Arrays -->
|
|
494
|
+
<h3 class="sub-heading"><i class="fa-solid fa-layer-group"></i> Arrays</h3>
|
|
495
|
+
<div class="compare" style="margin-bottom:2rem">
|
|
496
|
+
<div class="code-block">
|
|
497
|
+
<div class="code-block-header">
|
|
498
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
499
|
+
<span class="code-block-title">PlainScript</span>
|
|
500
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
501
|
+
</div>
|
|
502
|
+
<pre><code><span class="kw">remember</span> scores <span class="kw">as</span> [<span class="num">90</span>, <span class="num">85</span>, <span class="num">92</span>]
|
|
503
|
+
<span class="kw">show</span> scores[<span class="num">0</span>]
|
|
504
|
+
scores[<span class="num">1</span>] <span class="kw">becomes</span> <span class="num">95</span>
|
|
505
|
+
|
|
506
|
+
<span class="kw">show</span> <span class="kw">first</span> player <span class="kw">from</span> players
|
|
507
|
+
<span class="kw">show</span> <span class="kw">last</span> player <span class="kw">from</span> players
|
|
508
|
+
<span class="kw">show</span> players length
|
|
509
|
+
<span class="kw">add</span>(<span class="str">"Palmer"</span> <span class="kw">to</span> players)
|
|
510
|
+
<span class="kw">remove</span>(<span class="str">"Rodri"</span> <span class="kw">from</span> players)</code></pre>
|
|
511
|
+
</div>
|
|
512
|
+
<div class="code-block">
|
|
513
|
+
<div class="code-block-header">
|
|
514
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
515
|
+
<span class="code-block-title">JavaScript</span>
|
|
516
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
517
|
+
</div>
|
|
518
|
+
<pre><code><span class="kw">let</span> scores = [<span class="num">90</span>, <span class="num">85</span>, <span class="num">92</span>];
|
|
519
|
+
console.<span class="fn">log</span>(scores[<span class="num">0</span>]);
|
|
520
|
+
scores[<span class="num">1</span>] = <span class="num">95</span>;
|
|
521
|
+
|
|
522
|
+
console.<span class="fn">log</span>(players[<span class="num">0</span>]);
|
|
523
|
+
console.<span class="fn">log</span>(players[players.length - <span class="num">1</span>]);
|
|
524
|
+
console.<span class="fn">log</span>(players.length);
|
|
525
|
+
players.<span class="fn">push</span>(<span class="str">"Palmer"</span>);
|
|
526
|
+
players.<span class="fn">splice</span>(players.<span class="fn">indexOf</span>(<span class="str">"Rodri"</span>), <span class="num">1</span>);</code></pre>
|
|
527
|
+
</div>
|
|
528
|
+
</div>
|
|
529
|
+
|
|
530
|
+
<!-- Objects & Properties -->
|
|
531
|
+
<h3 class="sub-heading"><i class="fa-solid fa-cube"></i> Objects & Properties</h3>
|
|
532
|
+
<div class="compare" style="margin-bottom:2rem">
|
|
533
|
+
<div class="code-block">
|
|
534
|
+
<div class="code-block-header">
|
|
535
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
536
|
+
<span class="code-block-title">PlainScript</span>
|
|
537
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
538
|
+
</div>
|
|
539
|
+
<pre><code><span class="kw">remember</span> user <span class="kw">as</span>
|
|
540
|
+
name <span class="kw">is</span> <span class="str">"Ayokunle"</span>
|
|
541
|
+
age <span class="kw">is</span> <span class="num">17</span>
|
|
542
|
+
country <span class="kw">is</span> <span class="str">"Nigeria"</span>
|
|
543
|
+
<span class="kw">done</span>
|
|
544
|
+
|
|
545
|
+
<span class="kw">show</span> user.name
|
|
546
|
+
user.age <span class="kw">becomes</span> <span class="num">18</span>
|
|
547
|
+
|
|
548
|
+
<span class="kw">show</span> name <span class="kw">of</span> user
|
|
549
|
+
name <span class="kw">of</span> user <span class="kw">becomes</span> <span class="str">"Ayo"</span></code></pre>
|
|
550
|
+
</div>
|
|
551
|
+
<div class="code-block">
|
|
552
|
+
<div class="code-block-header">
|
|
553
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
554
|
+
<span class="code-block-title">JavaScript</span>
|
|
555
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
556
|
+
</div>
|
|
557
|
+
<pre><code><span class="kw">let</span> user = {
|
|
558
|
+
<span class="str">"name"</span>: <span class="str">"Ayokunle"</span>,
|
|
559
|
+
<span class="str">"age"</span>: <span class="num">17</span>,
|
|
560
|
+
<span class="str">"country"</span>: <span class="str">"Nigeria"</span>
|
|
561
|
+
};
|
|
562
|
+
|
|
563
|
+
console.<span class="fn">log</span>(user.name);
|
|
564
|
+
user.age = <span class="num">18</span>;
|
|
565
|
+
|
|
566
|
+
console.<span class="fn">log</span>(user.name);
|
|
567
|
+
user.name = <span class="str">"Ayo"</span>;</code></pre>
|
|
568
|
+
</div>
|
|
569
|
+
</div>
|
|
570
|
+
<div class="callout callout-info">
|
|
571
|
+
<i class="fa-solid fa-circle-info"></i>
|
|
572
|
+
<div class="callout-body">
|
|
573
|
+
<strong>Property chains</strong>
|
|
574
|
+
<p><code>of</code> chains right-to-left, so <code>city of address of customer</code> compiles to <code>customer.address.city</code>.</p>
|
|
575
|
+
</div>
|
|
576
|
+
</div>
|
|
577
|
+
|
|
578
|
+
<!-- Files -->
|
|
579
|
+
<h3 class="sub-heading" style="margin-top:2rem"><i class="fa-solid fa-file"></i> Files</h3>
|
|
580
|
+
<div class="compare" style="margin-bottom:2rem">
|
|
581
|
+
<div class="code-block">
|
|
582
|
+
<div class="code-block-header">
|
|
583
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
584
|
+
<span class="code-block-title">PlainScript</span>
|
|
585
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
586
|
+
</div>
|
|
587
|
+
<pre><code><span class="kw">remember</span> data <span class="kw">as</span> <span class="fn">read</span>(<span class="str">"users.txt"</span>)
|
|
588
|
+
<span class="fn">write</span>(data <span class="kw">to</span> <span class="str">"output.txt"</span>)
|
|
589
|
+
<span class="kw">show</span> <span class="fn">readFile</span>(<span class="str">"./config.json"</span>)</code></pre>
|
|
590
|
+
</div>
|
|
591
|
+
<div class="code-block">
|
|
592
|
+
<div class="code-block-header">
|
|
593
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
594
|
+
<span class="code-block-title">JavaScript</span>
|
|
595
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
596
|
+
</div>
|
|
597
|
+
<pre><code><span class="kw">let</span> data = <span class="fn">require</span>(<span class="str">'fs'</span>).<span class="fn">readFileSync</span>(<span class="str">'users.txt'</span>, <span class="str">'utf8'</span>);
|
|
598
|
+
<span class="fn">require</span>(<span class="str">'fs'</span>).<span class="fn">writeFileSync</span>(<span class="str">'output.txt'</span>, data);
|
|
599
|
+
console.<span class="fn">log</span>(<span class="fn">require</span>(<span class="str">'fs'</span>).<span class="fn">readFileSync</span>(<span class="str">'./config.json'</span>, <span class="str">'utf8'</span>));</code></pre>
|
|
600
|
+
</div>
|
|
601
|
+
</div>
|
|
602
|
+
|
|
603
|
+
<!-- Standard Library -->
|
|
604
|
+
<h3 class="sub-heading"><i class="fa-solid fa-box"></i> Standard Library</h3>
|
|
605
|
+
<p style="color:var(--muted);margin-bottom:.75rem">All standard library functions are available without any <code>use</code> or import statement.</p>
|
|
606
|
+
<div class="two-col-wide" style="margin-bottom:2rem">
|
|
607
|
+
<div>
|
|
608
|
+
<h4 style="margin-bottom:.5rem"><i class="fa-solid fa-terminal"></i> I/O & System</h4>
|
|
609
|
+
<div class="table-wrap">
|
|
610
|
+
<table>
|
|
611
|
+
<thead><tr><th>PlainScript</th><th>Compiles to</th></tr></thead>
|
|
612
|
+
<tbody>
|
|
613
|
+
<tr><td><code>print(x)</code></td><td><code>console.log(x)</code></td></tr>
|
|
614
|
+
<tr><td><code>show x</code></td><td><code>console.log(x)</code></td></tr>
|
|
615
|
+
<tr><td><code>env("KEY")</code></td><td><code>process.env["KEY"]</code></td></tr>
|
|
616
|
+
<tr><td><code>exit(code)</code></td><td><code>process.exit(code)</code></td></tr>
|
|
617
|
+
</tbody>
|
|
618
|
+
</table>
|
|
619
|
+
</div>
|
|
620
|
+
</div>
|
|
621
|
+
<div>
|
|
622
|
+
<h4 style="margin-bottom:.5rem"><i class="fa-solid fa-clock"></i> Time & Utilities</h4>
|
|
623
|
+
<div class="table-wrap">
|
|
624
|
+
<table>
|
|
625
|
+
<thead><tr><th>PlainScript</th><th>Compiles to</th></tr></thead>
|
|
626
|
+
<tbody>
|
|
627
|
+
<tr><td><code>time()</code></td><td><code>Date.now()</code></td></tr>
|
|
628
|
+
<tr><td><code>date()</code></td><td><code>new Date().toISOString()</code></td></tr>
|
|
629
|
+
<tr><td><code>sleep(ms)</code></td><td>Synchronous sleep via <code>Atomics.wait</code></td></tr>
|
|
630
|
+
<tr><td><code>uuid()</code></td><td><code>require('crypto').randomUUID()</code></td></tr>
|
|
631
|
+
</tbody>
|
|
632
|
+
</table>
|
|
633
|
+
</div>
|
|
634
|
+
</div>
|
|
635
|
+
</div>
|
|
636
|
+
<div class="two-col-wide" style="margin-bottom:2rem">
|
|
637
|
+
<div>
|
|
638
|
+
<h4 style="margin-bottom:.5rem"><i class="fa-solid fa-code"></i> JSON</h4>
|
|
639
|
+
<div class="table-wrap">
|
|
640
|
+
<table>
|
|
641
|
+
<thead><tr><th>PlainScript</th><th>Compiles to</th></tr></thead>
|
|
642
|
+
<tbody>
|
|
643
|
+
<tr><td><code>jsonEncode(value)</code></td><td><code>JSON.stringify(value)</code></td></tr>
|
|
644
|
+
<tr><td><code>jsonDecode(string)</code></td><td><code>JSON.parse(string)</code></td></tr>
|
|
645
|
+
</tbody>
|
|
646
|
+
</table>
|
|
647
|
+
</div>
|
|
648
|
+
</div>
|
|
649
|
+
<div>
|
|
650
|
+
<h4 style="margin-bottom:.5rem"><i class="fa-solid fa-font"></i> Strings & Numbers</h4>
|
|
651
|
+
<div class="table-wrap">
|
|
652
|
+
<table>
|
|
653
|
+
<thead><tr><th>PlainScript</th><th>Description</th></tr></thead>
|
|
654
|
+
<tbody>
|
|
655
|
+
<tr><td><code>length(x)</code></td><td>Length of a string or array</td></tr>
|
|
656
|
+
<tr><td><code>uppercase(x)</code></td><td>Convert to uppercase</td></tr>
|
|
657
|
+
<tr><td><code>lowercase(x)</code></td><td>Convert to lowercase</td></tr>
|
|
658
|
+
<tr><td><code>round(x)</code></td><td>Round to nearest integer</td></tr>
|
|
659
|
+
<tr><td><code>random()</code></td><td>Random float — <code>Math.random()</code></td></tr>
|
|
660
|
+
</tbody>
|
|
661
|
+
</table>
|
|
662
|
+
</div>
|
|
663
|
+
</div>
|
|
664
|
+
</div>
|
|
665
|
+
|
|
666
|
+
<!-- Imports -->
|
|
667
|
+
<h3 class="sub-heading"><i class="fa-solid fa-arrows-split-up-and-left"></i> Imports</h3>
|
|
668
|
+
<p style="color:var(--muted);margin-bottom:.75rem">Split a project across multiple <code>.pln</code> files using relative paths.</p>
|
|
669
|
+
<div class="code-block" style="margin-bottom:1rem">
|
|
670
|
+
<div class="code-block-header">
|
|
671
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
672
|
+
<span class="code-block-title">app.pln</span>
|
|
673
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
674
|
+
</div>
|
|
675
|
+
<pre><code><span class="kw">import</span> <span class="str">"./math.pln"</span>
|
|
676
|
+
<span class="kw">import</span> <span class="str">"./utils.pln"</span>
|
|
677
|
+
|
|
678
|
+
<span class="kw">show</span> <span class="fn">add</span>(<span class="num">3</span>, <span class="num">4</span>)</code></pre>
|
|
679
|
+
</div>
|
|
680
|
+
<div class="callout callout-info">
|
|
681
|
+
<i class="fa-solid fa-circle-info"></i>
|
|
682
|
+
<div class="callout-body">
|
|
683
|
+
<strong>Import rules</strong>
|
|
684
|
+
<p>Paths must be relative (<code>./</code> or <code>../</code>). Files compile in dependency order — deepest first. Circular imports produce a friendly compiler error.</p>
|
|
685
|
+
</div>
|
|
686
|
+
</div>
|
|
687
|
+
|
|
688
|
+
<!-- JavaScript Gateway -->
|
|
689
|
+
<h3 class="sub-heading"><i class="fa-solid fa-bolt"></i> JavaScript Gateway</h3>
|
|
690
|
+
<p style="color:var(--muted);margin-bottom:.75rem">Run raw JavaScript blocks, read input with <code>ask</code>, and use any npm package — including hyphenated and scoped names.</p>
|
|
691
|
+
<div class="compare" style="margin-bottom:2rem">
|
|
692
|
+
<div class="code-block">
|
|
693
|
+
<div class="code-block-header">
|
|
694
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
695
|
+
<span class="code-block-title">PlainScript</span>
|
|
696
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
697
|
+
</div>
|
|
698
|
+
<pre><code><span class="kw">remember</span> response <span class="kw">as javascript</span>
|
|
699
|
+
<span class="kw">const</span> res <span class="kw">= await</span> fetch(<span class="str">"https://api.example.com"</span>)
|
|
700
|
+
<span class="kw">const</span> data <span class="kw">= await</span> res.json()
|
|
701
|
+
<span class="kw">return</span> data
|
|
702
|
+
<span class="kw">done</span>
|
|
703
|
+
|
|
704
|
+
<span class="kw">ask</span> <span class="str">"What is your name?"</span> <span class="kw">as</span> name
|
|
705
|
+
<span class="kw">show</span> <span class="str">"Hello, "</span> + name
|
|
706
|
+
|
|
707
|
+
<span class="kw">use</span> node-fetch
|
|
708
|
+
<span class="kw">use</span> @scope/package-name</code></pre>
|
|
709
|
+
</div>
|
|
710
|
+
<div class="code-block">
|
|
711
|
+
<div class="code-block-header">
|
|
712
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
713
|
+
<span class="code-block-title">How it compiles</span>
|
|
714
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
715
|
+
</div>
|
|
716
|
+
<pre><code><span class="kw">let</span> response <span class="kw">= await</span> (<span class="kw">async</span> () => {
|
|
717
|
+
<span class="kw">const</span> res <span class="kw">= await</span> fetch(<span class="str">"https://api.example.com"</span>)
|
|
718
|
+
<span class="kw">const</span> data <span class="kw">= await</span> res.json()
|
|
719
|
+
<span class="kw">return</span> data
|
|
720
|
+
})();
|
|
721
|
+
|
|
722
|
+
<span class="kw">let</span> name <span class="kw">= await</span> __ask(<span class="str">"What is your name?"</span>);
|
|
723
|
+
console.<span class="fn">log</span>(<span class="str">"Hello, "</span> + name);
|
|
724
|
+
|
|
725
|
+
require(<span class="str">'node-fetch'</span>);
|
|
726
|
+
require(<span class="str">'@scope/package-name'</span>);</code></pre>
|
|
727
|
+
</div>
|
|
728
|
+
</div>
|
|
729
|
+
</div>
|
|
730
|
+
</section>
|
|
731
|
+
|
|
732
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
733
|
+
<!-- WEB DEVELOPMENT -->
|
|
734
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
735
|
+
<section class="section" id="web">
|
|
736
|
+
<div class="container">
|
|
737
|
+
<div class="section-tag"><i class="fa-solid fa-globe"></i> Web Development</div>
|
|
738
|
+
<h2 class="section-title">Express Developer Experience</h2>
|
|
739
|
+
<p class="section-lead">
|
|
740
|
+
Two styles of web server — choose the one that fits your mental model. Both compile to identical Express.js code.
|
|
741
|
+
</p>
|
|
742
|
+
|
|
743
|
+
<div class="compare" style="margin-bottom:2rem">
|
|
744
|
+
<div class="code-block">
|
|
745
|
+
<div class="code-block-header">
|
|
746
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
747
|
+
<span class="code-block-title">Shorthand style</span>
|
|
748
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
749
|
+
</div>
|
|
750
|
+
<pre><code><span class="kw">web app</span>
|
|
751
|
+
|
|
752
|
+
<span class="kw">serve folder</span> <span class="str">"public"</span>
|
|
753
|
+
|
|
754
|
+
<span class="kw">route</span> <span class="str">"/"</span>
|
|
755
|
+
<span class="kw">reply</span> <span class="str">"Hello from PlainScript!"</span>
|
|
756
|
+
<span class="kw">done</span>
|
|
757
|
+
|
|
758
|
+
<span class="kw">route</span> <span class="str">"/api/status"</span>
|
|
759
|
+
<span class="kw">reply json</span>
|
|
760
|
+
status <span class="kw">is</span> <span class="str">"ok"</span>
|
|
761
|
+
version <span class="kw">is</span> <span class="str">"1.0"</span>
|
|
762
|
+
<span class="kw">done</span>
|
|
763
|
+
<span class="kw">done</span>
|
|
764
|
+
|
|
765
|
+
<span class="kw">start</span> <span class="num">3000</span></code></pre>
|
|
766
|
+
</div>
|
|
767
|
+
<div class="code-block">
|
|
768
|
+
<div class="code-block-header">
|
|
769
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
770
|
+
<span class="code-block-title">Classic style — still supported</span>
|
|
771
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
772
|
+
</div>
|
|
773
|
+
<pre><code><span class="kw">use</span> express
|
|
774
|
+
|
|
775
|
+
<span class="kw">remember</span> app <span class="kw">as</span> <span class="fn">express</span>()
|
|
776
|
+
|
|
777
|
+
<span class="kw">serve folder</span> <span class="str">"public"</span>
|
|
778
|
+
|
|
779
|
+
<span class="kw">when someone visits</span> <span class="str">"/"</span>
|
|
780
|
+
<span class="kw">reply</span> <span class="str">"Hello from PlainScript!"</span>
|
|
781
|
+
<span class="kw">done</span>
|
|
782
|
+
|
|
783
|
+
<span class="kw">when someone visits</span> <span class="str">"/api/status"</span>
|
|
784
|
+
<span class="kw">reply json</span>
|
|
785
|
+
status <span class="kw">is</span> <span class="str">"ok"</span>
|
|
786
|
+
<span class="kw">done</span>
|
|
787
|
+
<span class="kw">done</span>
|
|
788
|
+
|
|
789
|
+
<span class="kw">listen on</span> <span class="num">3000</span>
|
|
790
|
+
<span class="kw">show</span> <span class="str">"Server running"</span>
|
|
791
|
+
<span class="kw">done</span></code></pre>
|
|
792
|
+
</div>
|
|
793
|
+
</div>
|
|
794
|
+
|
|
795
|
+
<h3 class="sub-heading"><i class="fa-solid fa-table-list"></i> Route reference</h3>
|
|
796
|
+
<div class="table-wrap">
|
|
797
|
+
<table>
|
|
798
|
+
<thead><tr><th>Construct</th><th>Compiles to</th><th>Notes</th></tr></thead>
|
|
799
|
+
<tbody>
|
|
800
|
+
<tr><td><code>web app</code></td><td><code>const app = require('express')()</code></td><td>Shorthand bootstrapper</td></tr>
|
|
801
|
+
<tr><td><code>route "/"</code></td><td><code>app.get("/", (req, res) => { ... })</code></td><td>GET route</td></tr>
|
|
802
|
+
<tr><td><code>when someone visits "/"</code></td><td><code>app.get("/", (req, res) => { ... })</code></td><td>Classic alias</td></tr>
|
|
803
|
+
<tr><td><code>reply "Hello"</code></td><td><code>res.send("Hello")</code></td><td></td></tr>
|
|
804
|
+
<tr><td><code>reply json … done</code></td><td><code>res.json({ ... })</code></td><td></td></tr>
|
|
805
|
+
<tr><td><code>serve folder "public"</code></td><td><code>app.use(express.static("public"))</code></td><td></td></tr>
|
|
806
|
+
<tr><td><code>start 3000</code></td><td><code>app.listen(3000)</code></td><td>Shorthand</td></tr>
|
|
807
|
+
<tr><td><code>listen on 3000 … done</code></td><td><code>app.listen(3000, () => { ... })</code></td><td>Classic with callback</td></tr>
|
|
808
|
+
<tr><td><code>request</code></td><td><code>req</code></td><td>Inside route bodies</td></tr>
|
|
809
|
+
<tr><td><code>response</code></td><td><code>res</code></td><td>Inside route bodies</td></tr>
|
|
810
|
+
</tbody>
|
|
811
|
+
</table>
|
|
812
|
+
</div>
|
|
813
|
+
|
|
814
|
+
<h3 class="sub-heading"><i class="fa-solid fa-route"></i> Routes & REST APIs</h3>
|
|
815
|
+
<p style="color:var(--muted);margin-bottom:.75rem">Define GET, POST, PUT, and DELETE routes with parameterised paths.</p>
|
|
816
|
+
<div class="code-block" style="margin-bottom:1.5rem">
|
|
817
|
+
<div class="code-block-header">
|
|
818
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
819
|
+
<span class="code-block-title">api.pln</span>
|
|
820
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
821
|
+
</div>
|
|
822
|
+
<pre><code><span class="kw">web app</span>
|
|
823
|
+
|
|
824
|
+
<span class="kw">route</span> <span class="str">"/api/users"</span>
|
|
825
|
+
<span class="kw">reply json</span>
|
|
826
|
+
users <span class="kw">is</span> [<span class="str">"Alice"</span>, <span class="str">"Bob"</span>]
|
|
827
|
+
<span class="kw">done</span>
|
|
828
|
+
<span class="kw">done</span>
|
|
829
|
+
|
|
830
|
+
<span class="kw">route</span> <span class="str">"/api/users/:id"</span>
|
|
831
|
+
<span class="kw">remember</span> id <span class="kw">as</span> request.params.id
|
|
832
|
+
<span class="kw">reply json</span>
|
|
833
|
+
user <span class="kw">is</span> id
|
|
834
|
+
<span class="kw">done</span>
|
|
835
|
+
<span class="kw">done</span>
|
|
836
|
+
|
|
837
|
+
<span class="kw">start</span> <span class="num">3000</span></code></pre>
|
|
838
|
+
</div>
|
|
839
|
+
</div>
|
|
840
|
+
</section>
|
|
841
|
+
|
|
842
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
843
|
+
<!-- HTTP -->
|
|
844
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
845
|
+
<section class="section section--alt" id="http">
|
|
846
|
+
<div class="container">
|
|
847
|
+
<div class="section-tag"><i class="fa-solid fa-globe"></i> HTTP</div>
|
|
848
|
+
<h2 class="section-title">HTTP Fetch</h2>
|
|
849
|
+
<p class="section-lead">
|
|
850
|
+
Make HTTP requests with the <code>fetch</code> keyword. Responses are accessed with dot notation and method calls.
|
|
851
|
+
</p>
|
|
852
|
+
|
|
853
|
+
<div class="compare" style="margin-bottom:2rem">
|
|
854
|
+
<div class="code-block">
|
|
855
|
+
<div class="code-block-header">
|
|
856
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
857
|
+
<span class="code-block-title">http.pln</span>
|
|
858
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
859
|
+
</div>
|
|
860
|
+
<pre><code><span class="kw">remember</span> response <span class="kw">as</span> <span class="kw">await</span> <span class="fn">fetch</span> <span class="str">"https://api.example.com/data"</span>
|
|
861
|
+
|
|
862
|
+
<span class="kw">if</span> response <span class="kw">is</span> ok
|
|
863
|
+
<span class="kw">remember</span> data <span class="kw">as</span> response.<span class="fn">json</span>()
|
|
864
|
+
<span class="kw">show</span> data
|
|
865
|
+
<span class="kw">otherwise</span>
|
|
866
|
+
<span class="kw">show</span> <span class="str">"Request failed"</span>
|
|
867
|
+
<span class="kw">done</span></code></pre>
|
|
868
|
+
</div>
|
|
869
|
+
<div class="code-block">
|
|
870
|
+
<div class="code-block-header">
|
|
871
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
872
|
+
<span class="code-block-title">Generated JavaScript</span>
|
|
873
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
874
|
+
</div>
|
|
875
|
+
<pre><code><span class="kw">let</span> response = <span class="kw">await</span> <span class="fn">fetch</span>(<span class="str">"https://api.example.com/data"</span>);
|
|
876
|
+
|
|
877
|
+
<span class="kw">if</span> (response.ok) {
|
|
878
|
+
<span class="kw">let</span> data = <span class="kw">await</span> response.<span class="fn">json</span>();
|
|
879
|
+
console.<span class="fn">log</span>(data);
|
|
880
|
+
} <span class="kw">else</span> {
|
|
881
|
+
console.<span class="fn">log</span>(<span class="str">"Request failed"</span>);
|
|
882
|
+
}</code></pre>
|
|
883
|
+
</div>
|
|
884
|
+
</div>
|
|
885
|
+
|
|
886
|
+
<div class="callout callout-info">
|
|
887
|
+
<i class="fa-solid fa-circle-info"></i>
|
|
888
|
+
<div class="callout-body">
|
|
889
|
+
<strong>Response methods</strong>
|
|
890
|
+
<p>Access <code>response.json()</code>, <code>response.text()</code>, and <code>response.status</code> with dot notation. The <code>is ok</code> comparison checks <code>response.ok</code>.</p>
|
|
891
|
+
</div>
|
|
892
|
+
</div>
|
|
893
|
+
</div>
|
|
894
|
+
</section>
|
|
895
|
+
|
|
896
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
897
|
+
<!-- TELEGRAM -->
|
|
898
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
899
|
+
<section class="section" id="telegram">
|
|
900
|
+
<div class="container">
|
|
901
|
+
<div class="section-tag"><i class="fa-brands fa-telegram"></i> Telegram </div>
|
|
902
|
+
<h2 class="section-title">Telegram Bot</h2>
|
|
903
|
+
<p class="section-lead">
|
|
904
|
+
Declarative bot syntax compiles to a dependency-free, polling-based Telegram runtime — commands, pattern matching, inline keyboards, and callback buttons.
|
|
905
|
+
</p>
|
|
906
|
+
|
|
907
|
+
<div class="compare" style="margin-bottom:2rem">
|
|
908
|
+
<div class="code-block">
|
|
909
|
+
<div class="code-block-header">
|
|
910
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
911
|
+
<span class="code-block-title">bot.pln</span>
|
|
912
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
913
|
+
</div>
|
|
914
|
+
<pre><code><span class="kw">remember</span> token <span class="kw">as</span> <span class="fn">env</span>(<span class="str">"BOT_TOKEN"</span>)
|
|
915
|
+
|
|
916
|
+
<span class="kw">bot</span> token
|
|
917
|
+
|
|
918
|
+
<span class="kw">when someone sends</span> <span class="str">"/start"</span>
|
|
919
|
+
<span class="kw">reply</span> <span class="str">"Hello from PlainScript!"</span>
|
|
920
|
+
<span class="kw">done</span>
|
|
921
|
+
|
|
922
|
+
<span class="cmt">// Inline keyboard buttons carry callback_data…</span>
|
|
923
|
+
<span class="kw">when someone sends</span> <span class="str">"/menu"</span>
|
|
924
|
+
<span class="kw">reply</span> <span class="str">"Choose an option:"</span> <span class="kw">with buttons</span>
|
|
925
|
+
<span class="str">"About"</span> -> <span class="str">"about"</span>, <span class="str">"Help"</span> -> <span class="str">"help"</span>
|
|
926
|
+
<span class="kw">done</span>
|
|
927
|
+
<span class="kw">done</span>
|
|
928
|
+
|
|
929
|
+
<span class="cmt">// …and pressing one executes its PlainScript handler.</span>
|
|
930
|
+
<span class="kw">when someone clicks</span> <span class="str">"about"</span>
|
|
931
|
+
<span class="kw">reply</span> <span class="str">"You clicked about!"</span>
|
|
932
|
+
<span class="kw">done</span>
|
|
933
|
+
|
|
934
|
+
<span class="kw">start telegram bot</span></code></pre>
|
|
935
|
+
</div>
|
|
936
|
+
<div class="code-block">
|
|
937
|
+
<div class="code-block-header">
|
|
938
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
939
|
+
<span class="code-block-title">Generated JavaScript (excerpt)</span>
|
|
940
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
941
|
+
</div>
|
|
942
|
+
<pre><code><span class="kw">const</span> Telegram = (() => {
|
|
943
|
+
<span class="cmt">// zero dependencies — plain fetch() against the Bot API</span>
|
|
944
|
+
<span class="kw">let</span> token = process.env.TELEGRAM_BOT_TOKEN;
|
|
945
|
+
<span class="kw">const</span> <span class="fn">call</span> = <span class="kw">async</span> (method, params) => { <span class="cmt">/* … */</span> };
|
|
946
|
+
|
|
947
|
+
<span class="kw">async function</span> <span class="fn">createTelegramBot</span>(botToken) {
|
|
948
|
+
<span class="cmt">// lives inside the module, so the handler</span>
|
|
949
|
+
<span class="cmt">// registry and transport are in scope; the token you</span>
|
|
950
|
+
<span class="cmt">// pass is bound to every API call.</span>
|
|
951
|
+
token = resolved;
|
|
952
|
+
<span class="kw">return</span> {
|
|
953
|
+
<span class="fn">onCommand</span>: (m, h) => handlers.command.push({ m, h }),
|
|
954
|
+
<span class="fn">onPattern</span>: (m, h) => handlers.pattern.push({ m, h }),
|
|
955
|
+
<span class="fn">onCallback</span>: (m, h) => handlers.callback.push({ m, h }),
|
|
956
|
+
<span class="fn">start</span>: <span class="kw">async</span> () => { <span class="cmt">/* getUpdates loop */</span> },
|
|
957
|
+
};
|
|
958
|
+
}
|
|
959
|
+
})();
|
|
960
|
+
|
|
961
|
+
BOT = <span class="kw">await</span> Telegram.<span class="fn">createTelegramBot</span>(token);
|
|
962
|
+
|
|
963
|
+
BOT.<span class="fn">onCommand</span>(<span class="str">"/start"</span>, <span class="kw">async</span> (ctx) => {
|
|
964
|
+
<span class="kw">await</span> Telegram.<span class="fn">sendMessage</span>(ctx.chatId, <span class="str">"Hello from PlainScript!"</span>);
|
|
965
|
+
});
|
|
966
|
+
|
|
967
|
+
BOT.<span class="fn">onCallback</span>(<span class="str">"about"</span>, <span class="kw">async</span> (ctx) => {
|
|
968
|
+
<span class="kw">await</span> Telegram.<span class="fn">sendMessage</span>(ctx.chatId, <span class="str">"You clicked about!"</span>);
|
|
969
|
+
});
|
|
970
|
+
|
|
971
|
+
<span class="kw">await</span> BOT.<span class="fn">start</span>();</code></pre>
|
|
972
|
+
</div>
|
|
973
|
+
</div>
|
|
974
|
+
|
|
975
|
+
<div class="callout callout-info">
|
|
976
|
+
<i class="fa-solid fa-circle-info"></i>
|
|
977
|
+
<div class="callout-body">
|
|
978
|
+
<strong>Aliases & version ranges</strong>
|
|
979
|
+
<p>The bot factory now lives inside the generated <code>Telegram</code> module, so rendered inline buttons execute their PlainScript callbacks correctly, and the token passed to <code>bot "…"</code> is used for every API call even without <code>TELEGRAM_BOT_TOKEN</code>. A regression test runs a real button press through the generated runtime.</p>
|
|
980
|
+
</div>
|
|
981
|
+
</div>
|
|
982
|
+
|
|
983
|
+
<h3 class="sub-heading"><i class="fa-solid fa-table-list"></i> Telegram syntax reference</h3>
|
|
984
|
+
<div class="table-wrap">
|
|
985
|
+
<table>
|
|
986
|
+
<thead><tr><th>PlainScript</th><th>Behavior</th></tr></thead>
|
|
987
|
+
<tbody>
|
|
988
|
+
<tr><td><code>bot "<token>"</code></td><td>Create the bot; binds <code>BOT</code>. Falls back to <code>TELEGRAM_BOT_TOKEN</code>.</td></tr>
|
|
989
|
+
<tr><td><code>when someone sends "/cmd" ... done</code></td><td>Exact command handler.</td></tr>
|
|
990
|
+
<tr><td><code>when someone sends "pattern *x*" ... done</code></td><td>Regex pattern handler with captures.</td></tr>
|
|
991
|
+
<tr><td><code>when someone clicks "data" ... done</code></td><td>Inline-button callback handler (<code>callback_query</code>).</td></tr>
|
|
992
|
+
<tr><td><code>reply "<text>" with buttons ... done</code></td><td>Inline keyboard; each row maps <code>"Label" -> "callback_data"</code>.</td></tr>
|
|
993
|
+
<tr><td><code>reply photo "<url>" [caption "…"]</code></td><td>Send a photo.</td></tr>
|
|
994
|
+
<tr><td><code>send message to chat ...</code></td><td>Proactive message to a known chat.</td></tr>
|
|
995
|
+
<tr><td><code>chats</code></td><td>List of chats seen by this bot.</td></tr>
|
|
996
|
+
<tr><td><code>start telegram bot</code></td><td>Start the long-polling loop.</td></tr>
|
|
997
|
+
</tbody>
|
|
998
|
+
</table>
|
|
999
|
+
</div>
|
|
1000
|
+
</div>
|
|
1001
|
+
</section>
|
|
1002
|
+
|
|
1003
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1004
|
+
<!-- WHATSAPP -->
|
|
1005
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1006
|
+
<section class="section section--alt" id="whatsapp">
|
|
1007
|
+
<div class="container">
|
|
1008
|
+
<div class="section-tag"><i class="fa-brands fa-whatsapp"></i> WhatsApp </div>
|
|
1009
|
+
<h2 class="section-title">WhatsApp Bots</h2>
|
|
1010
|
+
<p class="section-lead">
|
|
1011
|
+
Link a real WhatsApp account by QR scan or pairing code and answer messages in near-English. Baileys powers it behind the scenes — detected and installed automatically, never imported in your source.
|
|
1012
|
+
</p>
|
|
1013
|
+
|
|
1014
|
+
<div class="compare" style="margin-bottom:2rem">
|
|
1015
|
+
<div class="code-block">
|
|
1016
|
+
<div class="code-block-header">
|
|
1017
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1018
|
+
<span class="code-block-title">bot.pln</span>
|
|
1019
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1020
|
+
</div>
|
|
1021
|
+
<pre><code><span class="kw">whatsapp bot</span>
|
|
1022
|
+
<span class="kw">auth</span> <span class="str">"session"</span>
|
|
1023
|
+
<span class="kw">login pairing</span> <span class="str">"2348012345678"</span>
|
|
1024
|
+
|
|
1025
|
+
<span class="kw">on message</span>
|
|
1026
|
+
<span class="kw">log message</span>
|
|
1027
|
+
|
|
1028
|
+
<span class="kw">if</span> message.text <span class="kw">is</span> <span class="str">"/start"</span>
|
|
1029
|
+
<span class="kw">reply</span> <span class="str">"Welcome! Send /help for commands."</span>
|
|
1030
|
+
<span class="kw">done</span>
|
|
1031
|
+
|
|
1032
|
+
<span class="cmt">// Backtick strings keep line breaks…</span>
|
|
1033
|
+
<span class="kw">if</span> message.text <span class="kw">is</span> <span class="str">"/help"</span>
|
|
1034
|
+
<span class="kw">reply</span> <span class="str">`Available commands:
|
|
1035
|
+
/start - greet you
|
|
1036
|
+
/help - this message`</span>
|
|
1037
|
+
<span class="kw">done</span>
|
|
1038
|
+
<span class="kw">done</span>
|
|
1039
|
+
<span class="kw">done</span></code></pre>
|
|
1040
|
+
</div>
|
|
1041
|
+
<div class="code-block">
|
|
1042
|
+
<div class="code-block-header">
|
|
1043
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1044
|
+
<span class="code-block-title">Generated JavaScript (excerpt)</span>
|
|
1045
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1046
|
+
</div>
|
|
1047
|
+
<pre><code><span class="cmt">// Baileys runtime emitted by the compiler;</span>
|
|
1048
|
+
<span class="cmt">// the package is installed for you at build time.</span>
|
|
1049
|
+
<span class="kw">const</span> { __whatsappStart,
|
|
1050
|
+
__whatsappOnMessage,
|
|
1051
|
+
__whatsappReply } = (() => {
|
|
1052
|
+
<span class="cmt">/* makeWASocket, useMultiFileAuthState … */</span>
|
|
1053
|
+
})();
|
|
1054
|
+
|
|
1055
|
+
<span class="kw">await</span> __whatsappStart({
|
|
1056
|
+
folder: <span class="str">"session"</span>,
|
|
1057
|
+
login: { mode: <span class="str">'pairing'</span>, phone: <span class="str">"2348012345678"</span> }
|
|
1058
|
+
});
|
|
1059
|
+
|
|
1060
|
+
__whatsappOnMessage(<span class="kw">async</span> (__waCtx) => {
|
|
1061
|
+
console.<span class="fn">log</span>(__waCtx.message);
|
|
1062
|
+
<span class="kw">if</span> (__waCtx.message.text === <span class="str">"/start"</span>) {
|
|
1063
|
+
<span class="kw">await</span> __whatsappReply(__waCtx.chat,
|
|
1064
|
+
<span class="str">"Welcome! Send /help for commands."</span>);
|
|
1065
|
+
}
|
|
1066
|
+
});</code></pre>
|
|
1067
|
+
</div>
|
|
1068
|
+
</div>
|
|
1069
|
+
|
|
1070
|
+
<h3 class="sub-heading"><i class="fa-solid fa-link"></i> Linking a device</h3>
|
|
1071
|
+
<p>
|
|
1072
|
+
The first run prints either a QR code to render in your terminal or a pairing code like <code>D4PN-RX5C</code> to type into <em>WhatsApp → Settings → Linked Devices → Link with phone number instead</em>. Credentials are saved to your <code>auth</code> folder, so every later run reconnects silently until the device is unlinked.
|
|
1073
|
+
</p>
|
|
1074
|
+
|
|
1075
|
+
<div class="callout callout-info">
|
|
1076
|
+
<i class="fa-solid fa-circle-info"></i>
|
|
1077
|
+
<div class="callout-body">
|
|
1078
|
+
<strong>Lifecycle details</strong>
|
|
1079
|
+
<p>Your own outgoing messages and status broadcasts are filtered out of handlers. Unexpected disconnects auto-reconnect after ~3 seconds; a deliberately logged-out device stops cleanly with a clear error. Phone numbers are validated at compile time (8–15 digits).</p>
|
|
1080
|
+
</div>
|
|
1081
|
+
</div>
|
|
1082
|
+
|
|
1083
|
+
<h3 class="sub-heading"><i class="fa-solid fa-table-list"></i> WhatsApp syntax reference</h3>
|
|
1084
|
+
<div class="table-wrap">
|
|
1085
|
+
<table>
|
|
1086
|
+
<thead><tr><th>PlainScript</th><th>Behavior</th></tr></thead>
|
|
1087
|
+
<tbody>
|
|
1088
|
+
<tr><td><code>whatsapp bot ... done</code></td><td>Declare one bot and its handlers; it starts when the program runs.</td></tr>
|
|
1089
|
+
<tr><td><code>auth "<folder>"</code></td><td>Credential folder persisted across restarts (default <code>plainscript-whatsapp-auth</code>).</td></tr>
|
|
1090
|
+
<tr><td><code>login qr</code></td><td>Render a QR code in the terminal to link a device.</td></tr>
|
|
1091
|
+
<tr><td><code>login pairing "<number>"</code></td><td>Print an 8-character pairing code for the given phone number.</td></tr>
|
|
1092
|
+
<tr><td><code>on message ... done</code></td><td>Handler for every incoming text message.</td></tr>
|
|
1093
|
+
<tr><td><code>log message</code></td><td>Print the normalized message record.</td></tr>
|
|
1094
|
+
<tr><td><code>message.text · chat · sender · name · id · time · isGroup</code></td><td>Fields available inside the handler.</td></tr>
|
|
1095
|
+
<tr><td><code>reply "<value>"</code></td><td>Answer the current chat; non-string values are sent as JSON.</td></tr>
|
|
1096
|
+
</tbody>
|
|
1097
|
+
</table>
|
|
1098
|
+
</div>
|
|
1099
|
+
</div>
|
|
1100
|
+
</section>
|
|
1101
|
+
|
|
1102
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1103
|
+
<!-- WEBSOCKET -->
|
|
1104
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1105
|
+
<section class="section" id="websocket">
|
|
1106
|
+
<div class="container">
|
|
1107
|
+
<div class="section-tag"><i class="fa-solid fa-plug"></i> WebSocket</div>
|
|
1108
|
+
<h2 class="section-title">WebSocket Server</h2>
|
|
1109
|
+
<p class="section-lead">
|
|
1110
|
+
Build real-time WebSocket servers with the <code>websocket</code> keyword.
|
|
1111
|
+
</p>
|
|
1112
|
+
|
|
1113
|
+
<div class="compare" style="margin-bottom:2rem">
|
|
1114
|
+
<div class="code-block">
|
|
1115
|
+
<div class="code-block-header">
|
|
1116
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1117
|
+
<span class="code-block-title">ws.pln</span>
|
|
1118
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1119
|
+
</div>
|
|
1120
|
+
<pre><code><span class="kw">use</span> ws
|
|
1121
|
+
|
|
1122
|
+
<span class="kw">remember</span> server <span class="kw">as</span> <span class="kw">new</span> <span class="fn">WebSocketServer</span>(port: <span class="num">8080</span>)
|
|
1123
|
+
|
|
1124
|
+
<span class="kw">when someone connects</span>
|
|
1125
|
+
<span class="kw">show</span> <span class="str">"Client connected"</span>
|
|
1126
|
+
|
|
1127
|
+
<span class="kw">when they send</span> message
|
|
1128
|
+
<span class="kw">show</span> <span class="str">"Received: "</span> + message
|
|
1129
|
+
<span class="kw">send</span> <span class="str">"Echo: "</span> + message
|
|
1130
|
+
<span class="kw">done</span>
|
|
1131
|
+
|
|
1132
|
+
<span class="kw">when they disconnect</span>
|
|
1133
|
+
<span class="kw">show</span> <span class="str">"Client disconnected"</span>
|
|
1134
|
+
<span class="kw">done</span>
|
|
1135
|
+
<span class="kw">done</span></code></pre>
|
|
1136
|
+
</div>
|
|
1137
|
+
<div class="code-block">
|
|
1138
|
+
<div class="code-block-header">
|
|
1139
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1140
|
+
<span class="code-block-title">Generated JavaScript</span>
|
|
1141
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1142
|
+
</div>
|
|
1143
|
+
<pre><code><span class="kw">const</span> { <span class="fn">WebSocketServer</span> } = <span class="fn">require</span>(<span class="str">'ws'</span>);
|
|
1144
|
+
|
|
1145
|
+
<span class="kw">let</span> server = <span class="kw">new</span> <span class="fn">WebSocketServer</span>({ port: <span class="num">8080</span> });
|
|
1146
|
+
|
|
1147
|
+
server.<span class="fn">on</span>(<span class="str">'connection'</span>, (ws) => {
|
|
1148
|
+
console.<span class="fn">log</span>(<span class="str">"Client connected"</span>);
|
|
1149
|
+
|
|
1150
|
+
ws.<span class="fn">on</span>(<span class="str">'message'</span>, (message) => {
|
|
1151
|
+
console.<span class="fn">log</span>(<span class="str">"Received: "</span> + message);
|
|
1152
|
+
ws.<span class="fn">send</span>(<span class="str">"Echo: "</span> + message);
|
|
1153
|
+
});
|
|
1154
|
+
|
|
1155
|
+
ws.<span class="fn">on</span>(<span class="str">'close'</span>, () => {
|
|
1156
|
+
console.<span class="fn">log</span>(<span class="str">"Client disconnected"</span>);
|
|
1157
|
+
});
|
|
1158
|
+
});</code></pre>
|
|
1159
|
+
</div>
|
|
1160
|
+
</div>
|
|
1161
|
+
</div>
|
|
1162
|
+
</section>
|
|
1163
|
+
|
|
1164
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1165
|
+
<!-- SCHEDULING -->
|
|
1166
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1167
|
+
<section class="section section--alt" id="scheduling">
|
|
1168
|
+
<div class="container">
|
|
1169
|
+
<div class="section-tag"><i class="fa-solid fa-clock"></i> Scheduling</div>
|
|
1170
|
+
<h2 class="section-title">Cron Scheduling</h2>
|
|
1171
|
+
<p class="section-lead">
|
|
1172
|
+
Schedule recurring tasks with cron-style syntax using the <code>schedule</code> keyword.
|
|
1173
|
+
</p>
|
|
1174
|
+
|
|
1175
|
+
<div class="compare" style="margin-bottom:2rem">
|
|
1176
|
+
<div class="code-block">
|
|
1177
|
+
<div class="code-block-header">
|
|
1178
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1179
|
+
<span class="code-block-title">cron.pln</span>
|
|
1180
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1181
|
+
</div>
|
|
1182
|
+
<pre><code><span class="kw">use</span> node-cron
|
|
1183
|
+
|
|
1184
|
+
<span class="kw">schedule</span> <span class="str">"0 * * * *"</span>
|
|
1185
|
+
<span class="kw">show</span> <span class="str">"Hourly task ran at "</span> + <span class="fn">date</span>()
|
|
1186
|
+
<span class="kw">done</span>
|
|
1187
|
+
|
|
1188
|
+
<span class="kw">schedule</span> <span class="str">"*/5 * * * *"</span>
|
|
1189
|
+
<span class="kw">show</span> <span class="str">"Every 5 minutes"</span>
|
|
1190
|
+
<span class="kw">done</span></code></pre>
|
|
1191
|
+
</div>
|
|
1192
|
+
<div class="code-block">
|
|
1193
|
+
<div class="code-block-header">
|
|
1194
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1195
|
+
<span class="code-block-title">Generated JavaScript</span>
|
|
1196
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1197
|
+
</div>
|
|
1198
|
+
<pre><code><span class="kw">const</span> cron = <span class="fn">require</span>(<span class="str">'node-cron'</span>);
|
|
1199
|
+
|
|
1200
|
+
cron.<span class="fn">schedule</span>(<span class="str">"0 * * * *"</span>, () => {
|
|
1201
|
+
console.<span class="fn">log</span>(<span class="str">"Hourly task ran at "</span> + <span class="kw">new</span> Date().<span class="fn">toISOString</span>());
|
|
1202
|
+
});
|
|
1203
|
+
|
|
1204
|
+
cron.<span class="fn">schedule</span>(<span class="str">"*/5 * * * *"</span>, () => {
|
|
1205
|
+
console.<span class="fn">log</span>(<span class="str">"Every 5 minutes"</span>);
|
|
1206
|
+
});</code></pre>
|
|
1207
|
+
</div>
|
|
1208
|
+
</div>
|
|
1209
|
+
</div>
|
|
1210
|
+
</section>
|
|
1211
|
+
|
|
1212
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1213
|
+
<!-- EMAIL -->
|
|
1214
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1215
|
+
<section class="section" id="email">
|
|
1216
|
+
<div class="container">
|
|
1217
|
+
<div class="section-tag"><i class="fa-solid fa-envelope"></i> Email</div>
|
|
1218
|
+
<h2 class="section-title">Send Email</h2>
|
|
1219
|
+
<p class="section-lead">
|
|
1220
|
+
Send emails with the <code>send email</code> rule. Configure SMTP credentials through environment variables.
|
|
1221
|
+
</p>
|
|
1222
|
+
|
|
1223
|
+
<div class="compare" style="margin-bottom:2rem">
|
|
1224
|
+
<div class="code-block">
|
|
1225
|
+
<div class="code-block-header">
|
|
1226
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1227
|
+
<span class="code-block-title">email.pln</span>
|
|
1228
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1229
|
+
</div>
|
|
1230
|
+
<pre><code><span class="kw">remember</span> mailer <span class="kw">as</span> nodemailer
|
|
1231
|
+
host <span class="kw">is</span> <span class="str">"smtp.example.com"</span>
|
|
1232
|
+
port <span class="kw">is</span> <span class="num">587</span>
|
|
1233
|
+
user <span class="kw">is</span> <span class="fn">env</span>(<span class="str">"SMTP_USER"</span>)
|
|
1234
|
+
pass <span class="kw">is</span> <span class="fn">env</span>(<span class="str">"SMTP_PASS"</span>)
|
|
1235
|
+
<span class="kw">done</span>
|
|
1236
|
+
|
|
1237
|
+
<span class="kw">send email</span>
|
|
1238
|
+
from <span class="kw">is</span> <span class="str">"bot@example.com"</span>
|
|
1239
|
+
to <span class="kw">is</span> <span class="str">"user@example.com"</span>
|
|
1240
|
+
subject <span class="kw">is</span> <span class="str">"Hello from PlainScript"</span>
|
|
1241
|
+
body <span class="kw">is</span> <span class="str">"This email was sent from a PlainScript program."</span>
|
|
1242
|
+
<span class="kw">done</span></code></pre>
|
|
1243
|
+
</div>
|
|
1244
|
+
<div class="code-block">
|
|
1245
|
+
<div class="code-block-header">
|
|
1246
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1247
|
+
<span class="code-block-title">Generated JavaScript</span>
|
|
1248
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1249
|
+
</div>
|
|
1250
|
+
<pre><code><span class="kw">let</span> mailer = <span class="fn">require</span>(<span class="str">'nodemailer'</span>).<span class="fn">createTransport</span>({
|
|
1251
|
+
host: <span class="str">"smtp.example.com"</span>,
|
|
1252
|
+
port: <span class="num">587</span>,
|
|
1253
|
+
auth: {
|
|
1254
|
+
user: process.env[<span class="str">"SMTP_USER"</span>],
|
|
1255
|
+
pass: process.env[<span class="str">"SMTP_PASS"</span>]
|
|
1256
|
+
}
|
|
1257
|
+
});
|
|
1258
|
+
|
|
1259
|
+
<span class="kw">await</span> mailer.<span class="fn">sendMail</span>({
|
|
1260
|
+
from: <span class="str">"bot@example.com"</span>,
|
|
1261
|
+
to: <span class="str">"user@example.com"</span>,
|
|
1262
|
+
subject: <span class="str">"Hello from PlainScript"</span>,
|
|
1263
|
+
text: <span class="str">"This email was sent from a PlainScript program."</span>
|
|
1264
|
+
});</code></pre>
|
|
1265
|
+
</div>
|
|
1266
|
+
</div>
|
|
1267
|
+
</div>
|
|
1268
|
+
</section>
|
|
1269
|
+
|
|
1270
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1271
|
+
<!-- DATABASE -->
|
|
1272
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1273
|
+
<section class="section section--alt" id="database">
|
|
1274
|
+
<div class="container">
|
|
1275
|
+
<div class="section-tag"><i class="fa-solid fa-database"></i> Database</div>
|
|
1276
|
+
<h2 class="section-title">SQLite Developer Experience</h2>
|
|
1277
|
+
<p class="section-lead">
|
|
1278
|
+
Inline SQL blocks compile directly to <code>better-sqlite3</code> calls. No ORM. No query builder. Just SQL written naturally inside your PlainScript program.
|
|
1279
|
+
</p>
|
|
1280
|
+
|
|
1281
|
+
<div class="two-col-wide" style="margin-bottom:2rem">
|
|
1282
|
+
<div class="code-block">
|
|
1283
|
+
<div class="code-block-header">
|
|
1284
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1285
|
+
<span class="code-block-title">database.pln</span>
|
|
1286
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1287
|
+
</div>
|
|
1288
|
+
<pre><code><span class="kw">database</span> <span class="str">"app.db"</span>
|
|
1289
|
+
|
|
1290
|
+
<span class="kw">execute</span>
|
|
1291
|
+
CREATE TABLE IF NOT EXISTS users (
|
|
1292
|
+
id INTEGER PRIMARY KEY,
|
|
1293
|
+
name TEXT NOT NULL,
|
|
1294
|
+
age INTEGER
|
|
1295
|
+
)
|
|
1296
|
+
<span class="kw">done</span>
|
|
1297
|
+
|
|
1298
|
+
<span class="kw">insert</span>
|
|
1299
|
+
INSERT INTO users (name, age)
|
|
1300
|
+
VALUES ('Alice', 28)
|
|
1301
|
+
<span class="kw">done</span>
|
|
1302
|
+
|
|
1303
|
+
<span class="kw">query</span>
|
|
1304
|
+
SELECT * FROM users ORDER BY name
|
|
1305
|
+
<span class="kw">done</span>
|
|
1306
|
+
|
|
1307
|
+
<span class="kw">update</span>
|
|
1308
|
+
UPDATE users SET age = 29
|
|
1309
|
+
WHERE name = 'Alice'
|
|
1310
|
+
<span class="kw">done</span>
|
|
1311
|
+
|
|
1312
|
+
<span class="kw">delete</span>
|
|
1313
|
+
DELETE FROM users WHERE id = 1
|
|
1314
|
+
<span class="kw">done</span></code></pre>
|
|
1315
|
+
</div>
|
|
1316
|
+
<div>
|
|
1317
|
+
<h3 class="sub-heading" style="margin-top:0"><i class="fa-solid fa-table-list"></i> SQL block reference</h3>
|
|
1318
|
+
<div class="table-wrap">
|
|
1319
|
+
<table>
|
|
1320
|
+
<thead><tr><th>PlainScript</th><th>Compiles to</th></tr></thead>
|
|
1321
|
+
<tbody>
|
|
1322
|
+
<tr><td><code>database "file.db"</code></td><td><code>const db = new Database("file.db")</code></td></tr>
|
|
1323
|
+
<tr><td><code>query … done</code></td><td><code>db.prepare(`…`).all()</code></td></tr>
|
|
1324
|
+
<tr><td><code>insert … done</code></td><td><code>db.prepare(`…`).run()</code></td></tr>
|
|
1325
|
+
<tr><td><code>update … done</code></td><td><code>db.prepare(`…`).run()</code></td></tr>
|
|
1326
|
+
<tr><td><code>delete … done</code></td><td><code>db.prepare(`…`).run()</code></td></tr>
|
|
1327
|
+
<tr><td><code>execute … done</code></td><td><code>db.exec(`…`)</code></td></tr>
|
|
1328
|
+
</tbody>
|
|
1329
|
+
</table>
|
|
1330
|
+
</div>
|
|
1331
|
+
|
|
1332
|
+
<div class="callout callout-info" style="margin-top:1.25rem">
|
|
1333
|
+
<i class="fa-solid fa-circle-info"></i>
|
|
1334
|
+
<div class="callout-body">
|
|
1335
|
+
<strong>Classic style also works</strong>
|
|
1336
|
+
<p>You can also <code>use sqlite</code> and call <code>sqlite("database.db")</code> directly if you prefer the classic approach.</p>
|
|
1337
|
+
</div>
|
|
1338
|
+
</div>
|
|
1339
|
+
|
|
1340
|
+
<div class="callout callout-tip" style="margin-top:.75rem">
|
|
1341
|
+
<i class="fa-solid fa-circle-check"></i>
|
|
1342
|
+
<div class="callout-body">
|
|
1343
|
+
<strong>Zero configuration</strong>
|
|
1344
|
+
<p>SQLite files are created automatically if they don’t exist. No server to start, no credentials to manage.</p>
|
|
1345
|
+
</div>
|
|
1346
|
+
</div>
|
|
1347
|
+
</div>
|
|
1348
|
+
</div>
|
|
1349
|
+
</div>
|
|
1350
|
+
</section>
|
|
1351
|
+
|
|
1352
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1353
|
+
<!-- OCR -->
|
|
1354
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1355
|
+
<section class="section" id="ocr">
|
|
1356
|
+
<div class="container">
|
|
1357
|
+
<div class="section-tag"><i class="fa-solid fa-eye"></i> Vision </div>
|
|
1358
|
+
<h2 class="section-title">OCR — read text out of images</h2>
|
|
1359
|
+
<p class="section-lead">
|
|
1360
|
+
One sentence extracts text from scans, screenshots, and photos. Tesseract.js does the work; PlainScript keeps it out of your source.
|
|
1361
|
+
</p>
|
|
1362
|
+
|
|
1363
|
+
<div class="compare" style="margin-bottom:2rem">
|
|
1364
|
+
<div class="code-block">
|
|
1365
|
+
<div class="code-block-header">
|
|
1366
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1367
|
+
<span class="code-block-title">ocr.pln</span>
|
|
1368
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1369
|
+
</div>
|
|
1370
|
+
<pre><code><span class="cmt">// Extract text — mirrors ask "... as name"</span>
|
|
1371
|
+
<span class="kw">ocr</span> <span class="str">"scan.png"</span> <span class="kw">as</span> text
|
|
1372
|
+
<span class="kw">show</span> text
|
|
1373
|
+
|
|
1374
|
+
<span class="cmt">// Pick a language pack (default: "eng")</span>
|
|
1375
|
+
<span class="kw">ocr</span> <span class="str">"brief.png"</span> <span class="kw">as</span> inhalt <span class="kw">using</span> <span class="str">"deu"</span>
|
|
1376
|
+
<span class="kw">show</span> inhalt
|
|
1377
|
+
|
|
1378
|
+
<span class="cmt">// Combine packs, use any expression as the image</span>
|
|
1379
|
+
<span class="kw">remember</span> shot <span class="kw">as</span> <span class="str">"receipts/receipt-01.png"</span>
|
|
1380
|
+
<span class="kw">ocr</span> shot <span class="kw">as</span> total <span class="kw">using</span> <span class="str">"deu+eng"</span>
|
|
1381
|
+
|
|
1382
|
+
<span class="kw">if</span> total <span class="kw">contains</span> <span class="str">"INVOICE"</span>
|
|
1383
|
+
<span class="kw">show</span> <span class="str">"invoice detected"</span>
|
|
1384
|
+
<span class="kw">done</span></code></pre>
|
|
1385
|
+
</div>
|
|
1386
|
+
<div class="code-block">
|
|
1387
|
+
<div class="code-block-header">
|
|
1388
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1389
|
+
<span class="code-block-title">Generated JavaScript</span>
|
|
1390
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1391
|
+
</div>
|
|
1392
|
+
<pre><code><span class="kw">const</span> { <span class="fn">createWorker</span> } = <span class="fn">require</span>(<span class="str">'tesseract.js'</span>);
|
|
1393
|
+
|
|
1394
|
+
<span class="kw">async function</span> <span class="fn">__ocr</span>(imagePath, lang) {
|
|
1395
|
+
<span class="kw">const</span> worker = <span class="kw">await</span> <span class="fn">createWorker</span>(lang || <span class="str">'eng'</span>);
|
|
1396
|
+
<span class="kw">try</span> {
|
|
1397
|
+
<span class="kw">const</span> { data } = <span class="kw">await</span> worker.<span class="fn">recognize</span>(imagePath);
|
|
1398
|
+
<span class="kw">return</span> data.text;
|
|
1399
|
+
} <span class="kw">finally</span> {
|
|
1400
|
+
<span class="kw">await</span> worker.<span class="fn">terminate</span>();
|
|
1401
|
+
}
|
|
1402
|
+
}
|
|
1403
|
+
|
|
1404
|
+
<span class="kw">let</span> text = <span class="kw">await</span> <span class="fn">__ocr</span>(<span class="str">"scan.png"</span>, <span class="str">"eng"</span>);
|
|
1405
|
+
console.<span class="fn">log</span>(text);</code></pre>
|
|
1406
|
+
</div>
|
|
1407
|
+
</div>
|
|
1408
|
+
|
|
1409
|
+
<div class="two-col">
|
|
1410
|
+
<div>
|
|
1411
|
+
<h3 class="sub-heading"><i class="fa-solid fa-table-list"></i> Forms</h3>
|
|
1412
|
+
<div class="table-wrap">
|
|
1413
|
+
<table>
|
|
1414
|
+
<thead><tr><th>PlainScript</th><th>Behavior</th></tr></thead>
|
|
1415
|
+
<tbody>
|
|
1416
|
+
<tr><td><code>ocr "<image>" as <name></code></td><td>Extract text into <code><name></code> (English by default).</td></tr>
|
|
1417
|
+
<tr><td><code>... using "<lang>"</code></td><td>Tesseract language pack: <code>"deu"</code>, <code>"deu+eng"</code>, …</td></tr>
|
|
1418
|
+
</tbody>
|
|
1419
|
+
</table>
|
|
1420
|
+
</div>
|
|
1421
|
+
</div>
|
|
1422
|
+
<div>
|
|
1423
|
+
<div class="callout callout-info" style="margin-top:1.9rem">
|
|
1424
|
+
<i class="fa-solid fa-circle-info"></i>
|
|
1425
|
+
<div class="callout-body">
|
|
1426
|
+
<strong>tesseract.js stays out of your source</strong>
|
|
1427
|
+
<p>The implementation dependency is wired automatically: <code>plainscript install</code>, <code>plainscript run</code>, and <code>plainscript build</code> detect <code>ocr</code> statements and fetch <code>tesseract.js</code> for you. The statement is async like <code>ask</code> — top-level use wraps the program, and using it inside a function makes that function async.</p>
|
|
1428
|
+
</div>
|
|
1429
|
+
</div>
|
|
1430
|
+
</div>
|
|
1431
|
+
</div>
|
|
1432
|
+
</div>
|
|
1433
|
+
</section>
|
|
1434
|
+
|
|
1435
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1436
|
+
<!-- PACKAGES -->
|
|
1437
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1438
|
+
<section class="section section--alt" id="packages">
|
|
1439
|
+
<div class="container">
|
|
1440
|
+
<div class="section-tag"><i class="fa-solid fa-cubes"></i> Packages</div>
|
|
1441
|
+
<h2 class="section-title">npm, without the boilerplate</h2>
|
|
1442
|
+
<p class="section-lead">
|
|
1443
|
+
PlainScript wraps npm’s package manager to keep dependency management natural and minimal. Any npm package can be used in a PlainScript project.
|
|
1444
|
+
</p>
|
|
1445
|
+
|
|
1446
|
+
<div class="two-col" style="margin-bottom:2rem">
|
|
1447
|
+
<div>
|
|
1448
|
+
<h3 class="sub-heading"><i class="fa-solid fa-terminal"></i> Package commands</h3>
|
|
1449
|
+
<div class="cmd-strip"><span class="prm">$</span> <span class="cmd">plainscript add</span> <span class="arg">express</span></div>
|
|
1450
|
+
<div class="cmd-strip"><span class="prm">$</span> <span class="cmd">plainscript remove</span> <span class="arg">express</span></div>
|
|
1451
|
+
<div class="cmd-strip"><span class="prm">$</span> <span class="cmd">plainscript install</span></div>
|
|
1452
|
+
<div class="cmd-strip"><span class="prm">$</span> <span class="cmd">plainscript start</span></div>
|
|
1453
|
+
|
|
1454
|
+
<h3 class="sub-heading" style="margin-top:1.5rem"><i class="fa-solid fa-folder-open"></i> Project layout</h3>
|
|
1455
|
+
<p style="font-size:.95rem;line-height:1.6;color:#94a3b8;margin-bottom:1rem">PlainScript uses a zero-config convention. Place your source files in <code>src/</code> and compiled output goes to <code>dist/</code>. The entry point is <code>src/app.pln</code> by default. No configuration file is needed.</p>
|
|
1456
|
+
<div class="code-block">
|
|
1457
|
+
<div class="code-block-header">
|
|
1458
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1459
|
+
<span class="code-block-title">Default project structure</span>
|
|
1460
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1461
|
+
</div>
|
|
1462
|
+
<pre><code>myapp/
|
|
1463
|
+
src/
|
|
1464
|
+
app.pln <span class="cmt">// entry point</span>
|
|
1465
|
+
utils.pln <span class="cmt">// other modules</span>
|
|
1466
|
+
dist/ <span class="cmt">// compiled output (auto-generated)</span></code></pre>
|
|
1467
|
+
</div>
|
|
1468
|
+
</div>
|
|
1469
|
+
<div>
|
|
1470
|
+
<h3 class="sub-heading"><i class="fa-solid fa-plug"></i> Dependency detection</h3>
|
|
1471
|
+
<div class="table-wrap">
|
|
1472
|
+
<table>
|
|
1473
|
+
<thead><tr><th>PlainScript</th><th>Compiles to</th></tr></thead>
|
|
1474
|
+
<tbody>
|
|
1475
|
+
<tr><td><code>use express</code></td><td><code>const express = require('express')</code></td></tr>
|
|
1476
|
+
<tr><td><code>use sqlite</code></td><td><code>const Database = require('better-sqlite3')</code></td></tr>
|
|
1477
|
+
<tr><td><code>use fs</code></td><td><code>const fs = require('fs')</code></td></tr>
|
|
1478
|
+
<tr><td><code>use path</code></td><td><code>const path = require('path')</code></td></tr>
|
|
1479
|
+
<tr><td><code>web app</code></td><td><code>express</code> (automatic)</td></tr>
|
|
1480
|
+
<tr><td><code>ocr …</code></td><td><code>tesseract.js</code> (automatic)</td></tr>
|
|
1481
|
+
<tr><td><code>whatsapp bot</code> </td><td><code>@whiskeysockets/baileys</code> + <code>qrcode-terminal</code> (automatic)</td></tr>
|
|
1482
|
+
<tr><td><code>use axios</code></td><td><code>const axios = require('axios')</code></td></tr>
|
|
1483
|
+
<tr><td><code>use node-fetch</code></td><td><code>require('node-fetch')</code></td></tr>
|
|
1484
|
+
<tr><td><code>use @scope/package</code></td><td><code>require('@scope/package')</code></td></tr>
|
|
1485
|
+
<tr><td><code>use node-fetch as fetch</code> </td><td><code>const fetch = require('node-fetch')</code></td></tr>
|
|
1486
|
+
<tr><td><code>use left-pad@^1.3.0</code> </td><td><code>require('left-pad')</code> · installs <code>left-pad@^1.3.0</code></td></tr>
|
|
1487
|
+
<tr><td><code>use dotenv@16 as env</code> </td><td><code>const env = require('dotenv')</code></td></tr>
|
|
1488
|
+
<tr><td><code>use <any npm></code></td><td><code>require('<package>')</code></td></tr>
|
|
1489
|
+
</tbody>
|
|
1490
|
+
</table>
|
|
1491
|
+
</div>
|
|
1492
|
+
|
|
1493
|
+
<div class="callout callout-info" style="margin-top:1rem">
|
|
1494
|
+
<i class="fa-solid fa-tag"></i>
|
|
1495
|
+
<div class="callout-body">
|
|
1496
|
+
<strong>Aliases & version ranges</strong>
|
|
1497
|
+
<p>Hyphenated and scoped names can now bind to a variable with <code>as <name></code>, and any specifier may carry a version range (<code>@^1.3.0</code>, <code>@~2</code>, <code>@*</code>). Ranges flow through to installation; <code>require()</code> always uses the bare name. Aliasing PlainScript’s built-in runtime packages (<code>express</code>, <code>sqlite</code>, …) produces a friendly error instead of silent breakage.</p>
|
|
1498
|
+
</div>
|
|
1499
|
+
</div>
|
|
1500
|
+
|
|
1501
|
+
<div class="callout callout-warning" style="margin-top:1rem">
|
|
1502
|
+
<i class="fa-solid fa-triangle-exclamation"></i>
|
|
1503
|
+
<div class="callout-body">
|
|
1504
|
+
<strong>Automatic runtime dependencies</strong>
|
|
1505
|
+
<p>PlainScript detects <code>use</code>, <code>web app</code>, <code>ocr</code>, and database dependencies. <code>plainscript install</code>, <code>plainscript run</code>, and <code>plainscript build</code> install only missing npm packages — checked by bare name, installed with their full <code>name@range</code> specifier. Built-in Node modules are never installed.</p>
|
|
1506
|
+
</div>
|
|
1507
|
+
</div>
|
|
1508
|
+
</div>
|
|
1509
|
+
</div>
|
|
1510
|
+
</div>
|
|
1511
|
+
</section>
|
|
1512
|
+
|
|
1513
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1514
|
+
<!-- MULTI-FILE PROJECTS -->
|
|
1515
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1516
|
+
<section class="section" id="multi-file">
|
|
1517
|
+
<div class="container">
|
|
1518
|
+
<div class="section-tag"><i class="fa-solid fa-folder-tree"></i> Multi-file Projects</div>
|
|
1519
|
+
<h2 class="section-title">Imports & Dependency Ordering</h2>
|
|
1520
|
+
<p class="section-lead">
|
|
1521
|
+
Split a project across multiple <code>.pln</code> files. The compiler resolves dependencies automatically and compiles in the correct order.
|
|
1522
|
+
</p>
|
|
1523
|
+
|
|
1524
|
+
<div class="compare" style="margin-bottom:2rem">
|
|
1525
|
+
<div class="code-block">
|
|
1526
|
+
<div class="code-block-header">
|
|
1527
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1528
|
+
<span class="code-block-title">Project structure</span>
|
|
1529
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1530
|
+
</div>
|
|
1531
|
+
<pre><code>myapp/
|
|
1532
|
+
src/
|
|
1533
|
+
app.pln <span class="cmt">// entry point</span>
|
|
1534
|
+
math.pln <span class="cmt">// helper functions</span>
|
|
1535
|
+
utils.pln <span class="cmt">// utility functions</span>
|
|
1536
|
+
package.json <span class="cmt">// npm scripts: build, start</span>
|
|
1537
|
+
dist/ <span class="cmt">// generated JavaScript</span></code></pre>
|
|
1538
|
+
</div>
|
|
1539
|
+
<div class="code-block">
|
|
1540
|
+
<div class="code-block-header">
|
|
1541
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1542
|
+
<span class="code-block-title">app.pln</span>
|
|
1543
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1544
|
+
</div>
|
|
1545
|
+
<pre><code><span class="kw">import</span> <span class="str">"./math.pln"</span>
|
|
1546
|
+
<span class="kw">import</span> <span class="str">"./utils.pln"</span>
|
|
1547
|
+
|
|
1548
|
+
<span class="kw">show</span> <span class="fn">add</span>(<span class="num">3</span>, <span class="num">4</span>)
|
|
1549
|
+
<span class="kw">show</span> <span class="fn">uppercase</span>(<span class="str">"hello"</span>)</code></pre>
|
|
1550
|
+
</div>
|
|
1551
|
+
</div>
|
|
1552
|
+
|
|
1553
|
+
<div class="callout callout-info">
|
|
1554
|
+
<i class="fa-solid fa-circle-info"></i>
|
|
1555
|
+
<div class="callout-body">
|
|
1556
|
+
<strong>Import rules</strong>
|
|
1557
|
+
<p>Paths must be relative (<code>./</code> or <code>../</code>). Files compile in dependency order — deepest first. Circular imports produce a friendly compiler error.</p>
|
|
1558
|
+
</div>
|
|
1559
|
+
</div>
|
|
1560
|
+
</div>
|
|
1561
|
+
</section>
|
|
1562
|
+
|
|
1563
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1564
|
+
<!-- CLI REFERENCE -->
|
|
1565
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1566
|
+
<section class="section section--alt" id="cli">
|
|
1567
|
+
<div class="container">
|
|
1568
|
+
<div class="section-tag"><i class="fa-solid fa-terminal"></i> CLI Reference</div>
|
|
1569
|
+
<h2 class="section-title">All Commands</h2>
|
|
1570
|
+
<p class="section-lead">
|
|
1571
|
+
Everything the PlainScript compiler can do, from a single unified CLI.
|
|
1572
|
+
</p>
|
|
1573
|
+
|
|
1574
|
+
<div class="two-col-wide" style="margin-bottom:2rem">
|
|
1575
|
+
<div>
|
|
1576
|
+
<h3 class="sub-heading" style="margin-top:0"><i class="fa-solid fa-hammer"></i> Core</h3>
|
|
1577
|
+
<div class="table-wrap">
|
|
1578
|
+
<table>
|
|
1579
|
+
<thead><tr><th>Command</th><th>Description</th></tr></thead>
|
|
1580
|
+
<tbody>
|
|
1581
|
+
<tr><td><code>plainscript run <file.pln></code></td><td>Install missing dependencies, compile, and execute</td></tr>
|
|
1582
|
+
<tr><td><code>plainscript build <file.pln></code></td><td>Install missing dependencies and compile to <code>.js</code></td></tr>
|
|
1583
|
+
<tr><td><code>plainscript check <file.pln></code></td><td>Syntax check — exits 0 or 1</td></tr>
|
|
1584
|
+
<tr><td><code>plainscript fmt <file.pln></code></td><td>Format source in-place</td></tr>
|
|
1585
|
+
<tr><td><code>plainscript new [name]</code></td><td>Scaffold a new project</td></tr>
|
|
1586
|
+
<tr><td><code>plainscript start</code></td><td>Run <code>src/app.pln</code> and execute its <code>dist/</code> output</td></tr>
|
|
1587
|
+
<tr><td><code>plainscript doctor</code></td><td>Check the PlainScript environment and project dependencies</td></tr>
|
|
1588
|
+
<tr><td><code>plainscript version</code></td><td>Print the compiler version</td></tr>
|
|
1589
|
+
<tr><td><code>plainscript help</code></td><td>Show help text</td></tr>
|
|
1590
|
+
</tbody>
|
|
1591
|
+
</table>
|
|
1592
|
+
</div>
|
|
1593
|
+
|
|
1594
|
+
<h3 class="sub-heading" style="margin-top:1.5rem"><i class="fa-solid fa-cubes"></i> Packages</h3>
|
|
1595
|
+
<div class="table-wrap">
|
|
1596
|
+
<table>
|
|
1597
|
+
<thead><tr><th>Command</th><th>Description</th></tr></thead>
|
|
1598
|
+
<tbody>
|
|
1599
|
+
<tr><td><code>plainscript install</code></td><td>Detect and install missing runtime dependencies</td></tr>
|
|
1600
|
+
<tr><td><code>plainscript add <pkg></code></td><td>Install a package and record it</td></tr>
|
|
1601
|
+
<tr><td><code>plainscript remove <pkg></code></td><td>Uninstall a package</td></tr>
|
|
1602
|
+
<tr><td><code>plainscript update</code></td><td>Update all installed packages</td></tr>
|
|
1603
|
+
</tbody>
|
|
1604
|
+
</table>
|
|
1605
|
+
</div>
|
|
1606
|
+
</div>
|
|
1607
|
+
</div>
|
|
1608
|
+
</div>
|
|
1609
|
+
</section>
|
|
1610
|
+
|
|
1611
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1612
|
+
<!-- BACKEND SERVICES -->
|
|
1613
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1614
|
+
<section class="section" id="backend-services">
|
|
1615
|
+
<div class="container">
|
|
1616
|
+
<div class="section-tag"><i class="fa-solid fa-server"></i> Backend Services</div>
|
|
1617
|
+
<h2 class="section-title">Backend Services</h2>
|
|
1618
|
+
<p class="section-lead">
|
|
1619
|
+
Everything a backend needs, compiled deterministically — portable databases, an HTTP client, passwords and tokens, sessions, uploads, cookies, rate limiting, Google OAuth, custom 404s, error handling and retries. No rules, no AI, no hidden codegen.
|
|
1620
|
+
</p>
|
|
1621
|
+
|
|
1622
|
+
<div class="compare" style="margin-bottom:2rem">
|
|
1623
|
+
<div class="code-block">
|
|
1624
|
+
<div class="code-block-header">
|
|
1625
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1626
|
+
<span class="code-block-title">sessions.pln</span>
|
|
1627
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1628
|
+
</div>
|
|
1629
|
+
<pre><code><span class="kw">web app</span>
|
|
1630
|
+
<span class="kw">enable sessions</span> <span class="str">"a-long-random-secret"</span>
|
|
1631
|
+
|
|
1632
|
+
<span class="kw">route post</span> <span class="str">"/login"</span>
|
|
1633
|
+
user <span class="kw">of session of request becomes</span> username <span class="kw">of body of request</span>
|
|
1634
|
+
<span class="kw">reply</span> <span class="str">"welcome"</span>
|
|
1635
|
+
<span class="kw">done</span>
|
|
1636
|
+
|
|
1637
|
+
<span class="kw">route post</span> <span class="str">"/logout"</span>
|
|
1638
|
+
<span class="kw">destroy session</span>
|
|
1639
|
+
<span class="kw">reply</span> <span class="str">"bye"</span>
|
|
1640
|
+
<span class="kw">done</span></code></pre>
|
|
1641
|
+
</div>
|
|
1642
|
+
<div class="code-block">
|
|
1643
|
+
<div class="code-block-header">
|
|
1644
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1645
|
+
<span class="code-block-title">client.pln</span>
|
|
1646
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1647
|
+
</div>
|
|
1648
|
+
<pre><code><span class="kw">remember</span> r <span class="kw">as get</span> <span class="str">"https://api.example.com/users"</span>
|
|
1649
|
+
|
|
1650
|
+
<span class="kw">if</span> ok <span class="kw">of</span> r
|
|
1651
|
+
<span class="kw">show</span> status <span class="kw">of</span> r
|
|
1652
|
+
<span class="kw">show</span> data <span class="kw">of</span> r
|
|
1653
|
+
<span class="kw">done</span></code></pre>
|
|
1654
|
+
</div>
|
|
1655
|
+
</div>
|
|
1656
|
+
|
|
1657
|
+
<div class="feature-grid" style="margin-bottom:2rem">
|
|
1658
|
+
<div class="feature-card">
|
|
1659
|
+
<div class="feature-card-icon"><i class="fa-solid fa-database"></i></div>
|
|
1660
|
+
<h4>Portable databases</h4>
|
|
1661
|
+
<p><code>database "app.db"</code> probes the native driver and falls back to WebAssembly SQLite (<code>sql.js</code>). Pin it with <code>using "native"</code> or <code>using "wasm"</code>.</p>
|
|
1662
|
+
</div>
|
|
1663
|
+
<div class="feature-card">
|
|
1664
|
+
<div class="feature-card-icon"><i class="fa-solid fa-lock"></i></div>
|
|
1665
|
+
<h4>Passwords and tokens</h4>
|
|
1666
|
+
<p>scrypt hashing with <code>hashPassword</code>/<code>checkPassword</code>; HMAC-signed tokens with expiry via <code>createToken</code>/<code>readToken</code>.</p>
|
|
1667
|
+
</div>
|
|
1668
|
+
<div class="feature-card">
|
|
1669
|
+
<div class="feature-card-icon"><i class="fa-solid fa-file-arrow-up"></i></div>
|
|
1670
|
+
<h4>File uploads</h4>
|
|
1671
|
+
<p><code>accept uploads limit "5 MB" allow [...] folder "..."</code>; files surface as records with name, type, size, data and path (HTTP 413/415 enforced).</p>
|
|
1672
|
+
</div>
|
|
1673
|
+
<div class="feature-card">
|
|
1674
|
+
<div class="feature-card-icon"><i class="fa-solid fa-gauge-high"></i></div>
|
|
1675
|
+
<h4>Rate limiting and API keys</h4>
|
|
1676
|
+
<p><code>limit requests to 100 per minute</code> per-IP sliding window; <code>require api key from env("API_KEY")</code> fails closed.</p>
|
|
1677
|
+
</div>
|
|
1678
|
+
<div class="feature-card">
|
|
1679
|
+
<div class="feature-card-icon"><i class="fa-brands fa-google"></i></div>
|
|
1680
|
+
<h4>Google OAuth</h4>
|
|
1681
|
+
<p>A <code>google oauth</code> block registers redirect and callback endpoints and stores the signed-in user on the session.</p>
|
|
1682
|
+
</div>
|
|
1683
|
+
<div class="feature-card">
|
|
1684
|
+
<div class="feature-card-icon"><i class="fa-solid fa-rotate-left"></i></div>
|
|
1685
|
+
<h4>Error handling and retries</h4>
|
|
1686
|
+
<p><code>try ... recover ... done</code> catches failures; <code>retry 3 times every 5 seconds</code> re-runs flaky operations until they succeed.</p>
|
|
1687
|
+
</div>
|
|
1688
|
+
</div>
|
|
1689
|
+
</div>
|
|
1690
|
+
</section>
|
|
1691
|
+
|
|
1692
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1693
|
+
<!-- SECURITY -->
|
|
1694
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1695
|
+
<section class="section section--alt" id="security">
|
|
1696
|
+
<div class="container">
|
|
1697
|
+
<div class="section-tag"><i class="fa-solid fa-shield-halved"></i> Security</div>
|
|
1698
|
+
<h2 class="section-title">Security Model</h2>
|
|
1699
|
+
<p class="section-lead">
|
|
1700
|
+
PlainScript compiles deterministically — the JavaScript you run is the JavaScript you can read. The compiler adds multiple layers of validation so projects stay safe and predictable.
|
|
1701
|
+
</p>
|
|
1702
|
+
|
|
1703
|
+
<div class="feature-grid" style="margin-bottom:2rem">
|
|
1704
|
+
<div class="feature-card">
|
|
1705
|
+
<div class="feature-card-icon"><i class="fa-solid fa-code"></i></div>
|
|
1706
|
+
<h4>Readable output</h4>
|
|
1707
|
+
<p>Every construct compiles to plain, inspectable JavaScript. Nothing hidden, nothing generated behind your back — <code>plainscript build</code> shows you exactly what will run.</p>
|
|
1708
|
+
</div>
|
|
1709
|
+
<div class="feature-card">
|
|
1710
|
+
<div class="feature-card-icon"><i class="fa-solid fa-ban"></i></div>
|
|
1711
|
+
<h4>Dependency restrictions</h4>
|
|
1712
|
+
<p>Packages referenced by <code>use</code> must be declared and installed. Missing dependencies stop compilation with a friendly error instead of failing at runtime.</p>
|
|
1713
|
+
</div>
|
|
1714
|
+
<div class="feature-card">
|
|
1715
|
+
<div class="feature-card-icon"><i class="fa-solid fa-bug-slash"></i></div>
|
|
1716
|
+
<h4>Teaching errors</h4>
|
|
1717
|
+
<p>The compiler rejects ambiguous or invalid programs at compile time with clear messages — including route-only features used outside routes and sessions used without <code>enable sessions</code>.</p>
|
|
1718
|
+
</div>
|
|
1719
|
+
<div class="feature-card">
|
|
1720
|
+
<div class="feature-card-icon"><i class="fa-solid fa-key"></i></div>
|
|
1721
|
+
<h4>Environment secrets</h4>
|
|
1722
|
+
<p>API keys and tokens are read from environment variables via <code>env()</code> at runtime. Secret values never live in PlainScript source code.</p>
|
|
1723
|
+
</div>
|
|
1724
|
+
<div class="feature-card">
|
|
1725
|
+
<div class="feature-card-icon"><i class="fa-solid fa-file-shield"></i></div>
|
|
1726
|
+
<h4>.env support</h4>
|
|
1727
|
+
<p>PlainScript loads <code>.env</code> files automatically via <code>dotenv</code>. Environment variables are available through <code>env("KEY")</code> in PlainScript code.</p>
|
|
1728
|
+
</div>
|
|
1729
|
+
<div class="feature-card">
|
|
1730
|
+
<div class="feature-card-icon"><i class="fa-solid fa-shield-halved"></i></div>
|
|
1731
|
+
<h4>Hardened web primitives</h4>
|
|
1732
|
+
<p>Passwords use salted scrypt with constant-time verification, tokens are HMAC-signed with expiry, API-key checks fail closed, and sessions ride HttpOnly cookies.</p>
|
|
1733
|
+
</div>
|
|
1734
|
+
</div>
|
|
1735
|
+
</div>
|
|
1736
|
+
</section>
|
|
1737
|
+
|
|
1738
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1739
|
+
<!-- EXAMPLES -->
|
|
1740
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
1741
|
+
<section class="section" id="examples">
|
|
1742
|
+
<div class="container">
|
|
1743
|
+
<div class="section-tag"><i class="fa-solid fa-terminal"></i> Examples</div>
|
|
1744
|
+
<h2 class="section-title">PlainScript in action</h2>
|
|
1745
|
+
<p class="section-lead">
|
|
1746
|
+
Real programs written in PlainScript. Every example compiles to clean, readable JavaScript.
|
|
1747
|
+
</p>
|
|
1748
|
+
|
|
1749
|
+
<!-- 1. CLI Hello World -->
|
|
1750
|
+
<h3 class="sub-heading"><i class="fa-solid fa-hand-sparkles"></i> CLI Hello World</h3>
|
|
1751
|
+
<div class="compare" style="margin-bottom:2rem">
|
|
1752
|
+
<div class="code-block">
|
|
1753
|
+
<div class="code-block-header">
|
|
1754
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1755
|
+
<span class="code-block-title">hello.pln</span>
|
|
1756
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1757
|
+
</div>
|
|
1758
|
+
<pre><code><span class="kw">remember</span> name <span class="kw">as</span> <span class="str">"World"</span>
|
|
1759
|
+
<span class="kw">show</span> <span class="str">"Hello, "</span> + name</code></pre>
|
|
1760
|
+
</div>
|
|
1761
|
+
<div class="code-block">
|
|
1762
|
+
<div class="code-block-header">
|
|
1763
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1764
|
+
<span class="code-block-title">Terminal</span>
|
|
1765
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1766
|
+
</div>
|
|
1767
|
+
<pre><code><span class="prm">$</span> plainscript run hello.pln
|
|
1768
|
+
Hello, World!</code></pre>
|
|
1769
|
+
</div>
|
|
1770
|
+
</div>
|
|
1771
|
+
|
|
1772
|
+
<!-- 2. Calculator -->
|
|
1773
|
+
<h3 class="sub-heading"><i class="fa-solid fa-calculator"></i> Calculator</h3>
|
|
1774
|
+
<div class="compare" style="margin-bottom:2rem">
|
|
1775
|
+
<div class="code-block">
|
|
1776
|
+
<div class="code-block-header">
|
|
1777
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1778
|
+
<span class="code-block-title">calc.pln</span>
|
|
1779
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1780
|
+
</div>
|
|
1781
|
+
<pre><code><span class="kw">make</span> <span class="fn">add</span>(a, b)
|
|
1782
|
+
<span class="kw">give</span> a + b
|
|
1783
|
+
<span class="kw">done</span>
|
|
1784
|
+
|
|
1785
|
+
<span class="kw">make</span> <span class="fn">multiply</span>(a, b)
|
|
1786
|
+
<span class="kw">give</span> a * b
|
|
1787
|
+
<span class="kw">done</span>
|
|
1788
|
+
|
|
1789
|
+
<span class="kw">show</span> <span class="fn">add</span>(<span class="num">5</span>, <span class="num">3</span>)
|
|
1790
|
+
<span class="kw">show</span> <span class="fn">multiply</span>(<span class="num">4</span>, <span class="num">7</span>)</code></pre>
|
|
1791
|
+
</div>
|
|
1792
|
+
<div class="code-block">
|
|
1793
|
+
<div class="code-block-header">
|
|
1794
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1795
|
+
<span class="code-block-title">Terminal</span>
|
|
1796
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1797
|
+
</div>
|
|
1798
|
+
<pre><code><span class="prm">$</span> plainscript run calc.pln
|
|
1799
|
+
8
|
|
1800
|
+
28</code></pre>
|
|
1801
|
+
</div>
|
|
1802
|
+
</div>
|
|
1803
|
+
|
|
1804
|
+
<!-- 3. File Processing -->
|
|
1805
|
+
<h3 class="sub-heading"><i class="fa-solid fa-file-lines"></i> File Processing</h3>
|
|
1806
|
+
<div class="code-block" style="margin-bottom:2rem">
|
|
1807
|
+
<div class="code-block-header">
|
|
1808
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1809
|
+
<span class="code-block-title">files.pln</span>
|
|
1810
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1811
|
+
</div>
|
|
1812
|
+
<pre><code><span class="kw">remember</span> data <span class="kw">as</span> <span class="fn">read</span>(<span class="str">"input.txt"</span>)
|
|
1813
|
+
<span class="kw">remember</span> upper <span class="kw">as</span> <span class="fn">uppercase</span>(data)
|
|
1814
|
+
<span class="fn">write</span>(upper <span class="kw">to</span> <span class="str">"output.txt"</span>)
|
|
1815
|
+
<span class="kw">show</span> <span class="str">"File processed. Lines: "</span> + <span class="fn">length</span>(data)</code></pre>
|
|
1816
|
+
</div>
|
|
1817
|
+
|
|
1818
|
+
<!-- 4. REST API -->
|
|
1819
|
+
<h3 class="sub-heading"><i class="fa-solid fa-server"></i> REST API</h3>
|
|
1820
|
+
<div class="code-block" style="margin-bottom:2rem">
|
|
1821
|
+
<div class="code-block-header">
|
|
1822
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1823
|
+
<span class="code-block-title">api.pln</span>
|
|
1824
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1825
|
+
</div>
|
|
1826
|
+
<pre><code><span class="kw">web app</span>
|
|
1827
|
+
|
|
1828
|
+
<span class="kw">remember</span> todos <span class="kw">as</span> []
|
|
1829
|
+
|
|
1830
|
+
<span class="kw">route</span> <span class="str">"/api/todos"</span>
|
|
1831
|
+
<span class="kw">reply json</span>
|
|
1832
|
+
todos <span class="kw">is</span> todos
|
|
1833
|
+
<span class="kw">done</span>
|
|
1834
|
+
<span class="kw">done</span>
|
|
1835
|
+
|
|
1836
|
+
<span class="kw">route</span> <span class="str">"/"</span>
|
|
1837
|
+
<span class="kw">reply</span> <span class="str">"Todo API running"</span>
|
|
1838
|
+
<span class="kw">done</span>
|
|
1839
|
+
|
|
1840
|
+
<span class="kw">start</span> <span class="num">3000</span></code></pre>
|
|
1841
|
+
</div>
|
|
1842
|
+
|
|
1843
|
+
<!-- 5. REST API fetching multiple APIs -->
|
|
1844
|
+
<h3 class="sub-heading"><i class="fa-solid fa-arrows-rotate"></i> Fetching Multiple APIs</h3>
|
|
1845
|
+
<div class="code-block" style="margin-bottom:2rem">
|
|
1846
|
+
<div class="code-block-header">
|
|
1847
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1848
|
+
<span class="code-block-title">multi-fetch.pln</span>
|
|
1849
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1850
|
+
</div>
|
|
1851
|
+
<pre><code><span class="kw">remember</span> users <span class="kw">as</span> <span class="kw">await</span> <span class="fn">fetch</span> <span class="str">"https://jsonplaceholder.typicode.com/users"</span>
|
|
1852
|
+
<span class="kw">remember</span> posts <span class="kw">as</span> <span class="kw">await</span> <span class="fn">fetch</span> <span class="str">"https://jsonplaceholder.typicode.com/posts"</span>
|
|
1853
|
+
|
|
1854
|
+
<span class="kw">if</span> users <span class="kw">is</span> ok <span class="kw">and</span> posts <span class="kw">is</span> ok
|
|
1855
|
+
<span class="kw">remember</span> userData <span class="kw">as</span> users.<span class="fn">json</span>()
|
|
1856
|
+
<span class="kw">remember</span> postData <span class="kw">as</span> posts.<span class="fn">json</span>()
|
|
1857
|
+
<span class="kw">show</span> <span class="str">"Users: "</span> + <span class="fn">length</span>(userData)
|
|
1858
|
+
<span class="kw">show</span> <span class="str">"Posts: "</span> + <span class="fn">length</span>(postData)
|
|
1859
|
+
<span class="kw">otherwise</span>
|
|
1860
|
+
<span class="kw">show</span> <span class="str">"One or more API calls failed"</span>
|
|
1861
|
+
<span class="kw">done</span></code></pre>
|
|
1862
|
+
</div>
|
|
1863
|
+
|
|
1864
|
+
<!-- 6. Telegram Bot -->
|
|
1865
|
+
<h3 class="sub-heading"><i class="fa-brands fa-telegram"></i> Telegram Bot</h3>
|
|
1866
|
+
<div class="code-block" style="margin-bottom:2rem">
|
|
1867
|
+
<div class="code-block-header">
|
|
1868
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1869
|
+
<span class="code-block-title">telegram.pln</span>
|
|
1870
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1871
|
+
</div>
|
|
1872
|
+
<pre><code><span class="kw">remember</span> token <span class="kw">as</span> <span class="fn">env</span>(<span class="str">"BOT_TOKEN"</span>)
|
|
1873
|
+
<span class="kw">remember</span> bot <span class="kw">as</span> telegram bot with token
|
|
1874
|
+
|
|
1875
|
+
<span class="kw">when someone sends</span> <span class="str">"/start"</span>
|
|
1876
|
+
<span class="kw">reply</span> <span class="str">"Welcome to the PlainScript bot!"</span>
|
|
1877
|
+
<span class="kw">done</span>
|
|
1878
|
+
|
|
1879
|
+
<span class="kw">when someone sends</span> <span class="str">"/echo"</span>
|
|
1880
|
+
<span class="kw">reply</span> <span class="str">"You said: "</span> + message
|
|
1881
|
+
<span class="kw">done</span></code></pre>
|
|
1882
|
+
</div>
|
|
1883
|
+
|
|
1884
|
+
<!-- 7. WebSocket Server -->
|
|
1885
|
+
<h3 class="sub-heading"><i class="fa-solid fa-plug"></i> WebSocket Server</h3>
|
|
1886
|
+
<div class="code-block" style="margin-bottom:2rem">
|
|
1887
|
+
<div class="code-block-header">
|
|
1888
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1889
|
+
<span class="code-block-title">ws.pln</span>
|
|
1890
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1891
|
+
</div>
|
|
1892
|
+
<pre><code><span class="kw">use</span> ws
|
|
1893
|
+
|
|
1894
|
+
<span class="kw">remember</span> server <span class="kw">as</span> <span class="kw">new</span> <span class="fn">WebSocketServer</span>(port: <span class="num">8080</span>)
|
|
1895
|
+
|
|
1896
|
+
<span class="kw">when someone connects</span>
|
|
1897
|
+
<span class="kw">show</span> <span class="str">"Client connected"</span>
|
|
1898
|
+
<span class="kw">when they send</span> message
|
|
1899
|
+
<span class="kw">send</span> <span class="str">"Echo: "</span> + message
|
|
1900
|
+
<span class="kw">done</span>
|
|
1901
|
+
<span class="kw">done</span></code></pre>
|
|
1902
|
+
</div>
|
|
1903
|
+
|
|
1904
|
+
<!-- 8. Scheduled Task -->
|
|
1905
|
+
<h3 class="sub-heading"><i class="fa-solid fa-clock"></i> Scheduled Task</h3>
|
|
1906
|
+
<div class="code-block" style="margin-bottom:2rem">
|
|
1907
|
+
<div class="code-block-header">
|
|
1908
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1909
|
+
<span class="code-block-title">cron.pln</span>
|
|
1910
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1911
|
+
</div>
|
|
1912
|
+
<pre><code><span class="kw">use</span> node-cron
|
|
1913
|
+
|
|
1914
|
+
<span class="kw">schedule</span> <span class="str">"0 9 * * *"</span>
|
|
1915
|
+
<span class="kw">show</span> <span class="str">"Daily 9am task ran at "</span> + <span class="fn">date</span>()
|
|
1916
|
+
<span class="kw">done</span></code></pre>
|
|
1917
|
+
</div>
|
|
1918
|
+
|
|
1919
|
+
<!-- 9. Email -->
|
|
1920
|
+
<h3 class="sub-heading"><i class="fa-solid fa-envelope"></i> Email</h3>
|
|
1921
|
+
<div class="code-block" style="margin-bottom:2rem">
|
|
1922
|
+
<div class="code-block-header">
|
|
1923
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1924
|
+
<span class="code-block-title">email.pln</span>
|
|
1925
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1926
|
+
</div>
|
|
1927
|
+
<pre><code><span class="kw">use</span> nodemailer
|
|
1928
|
+
|
|
1929
|
+
<span class="kw">remember</span> transporter <span class="kw">as</span> <span class="fn">createTransport</span>({
|
|
1930
|
+
host: <span class="str">"smtp.example.com"</span>,
|
|
1931
|
+
port: <span class="num">587</span>
|
|
1932
|
+
})
|
|
1933
|
+
|
|
1934
|
+
<span class="kw">send email</span>
|
|
1935
|
+
from <span class="kw">is</span> <span class="str">"me@example.com"</span>
|
|
1936
|
+
to <span class="kw">is</span> <span class="str">"you@example.com"</span>
|
|
1937
|
+
subject <span class="kw">is</span> <span class="str">"Test"</span>
|
|
1938
|
+
body <span class="kw">is</span> <span class="str">"Hello from PlainScript!"</span>
|
|
1939
|
+
<span class="kw">done</span></code></pre>
|
|
1940
|
+
</div>
|
|
1941
|
+
|
|
1942
|
+
<!-- 10. Database-backed API -->
|
|
1943
|
+
<h3 class="sub-heading"><i class="fa-solid fa-database"></i> Database-backed API</h3>
|
|
1944
|
+
<div class="code-block" style="margin-bottom:2rem">
|
|
1945
|
+
<div class="code-block-header">
|
|
1946
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1947
|
+
<span class="code-block-title">db-api.pln</span>
|
|
1948
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1949
|
+
</div>
|
|
1950
|
+
<pre><code><span class="kw">web app</span>
|
|
1951
|
+
<span class="kw">database</span> <span class="str">"app.db"</span>
|
|
1952
|
+
|
|
1953
|
+
<span class="kw">execute</span>
|
|
1954
|
+
CREATE TABLE IF NOT EXISTS items (
|
|
1955
|
+
id INTEGER PRIMARY KEY,
|
|
1956
|
+
name TEXT NOT NULL
|
|
1957
|
+
)
|
|
1958
|
+
<span class="kw">done</span>
|
|
1959
|
+
|
|
1960
|
+
<span class="kw">route</span> <span class="str">"/items"</span>
|
|
1961
|
+
<span class="kw">remember</span> rows <span class="kw">as</span> query
|
|
1962
|
+
SELECT * FROM items
|
|
1963
|
+
<span class="kw">done</span>
|
|
1964
|
+
<span class="kw">reply json</span>
|
|
1965
|
+
items <span class="kw">is</span> rows
|
|
1966
|
+
<span class="kw">done</span>
|
|
1967
|
+
<span class="kw">done</span>
|
|
1968
|
+
|
|
1969
|
+
<span class="kw">start</span> <span class="num">3000</span></code></pre>
|
|
1970
|
+
</div>
|
|
1971
|
+
|
|
1972
|
+
<!-- 11. Multi-file Application -->
|
|
1973
|
+
<h3 class="sub-heading"><i class="fa-solid fa-folder-tree"></i> Multi-file Application</h3>
|
|
1974
|
+
<div class="compare" style="margin-bottom:2rem">
|
|
1975
|
+
<div class="code-block">
|
|
1976
|
+
<div class="code-block-header">
|
|
1977
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1978
|
+
<span class="code-block-title">math.pln</span>
|
|
1979
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1980
|
+
</div>
|
|
1981
|
+
<pre><code><span class="kw">make</span> <span class="fn">add</span>(a, b)
|
|
1982
|
+
<span class="kw">give</span> a + b
|
|
1983
|
+
<span class="kw">done</span>
|
|
1984
|
+
|
|
1985
|
+
<span class="kw">make</span> <span class="fn">multiply</span>(a, b)
|
|
1986
|
+
<span class="kw">give</span> a * b
|
|
1987
|
+
<span class="kw">done</span></code></pre>
|
|
1988
|
+
</div>
|
|
1989
|
+
<div class="code-block">
|
|
1990
|
+
<div class="code-block-header">
|
|
1991
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
1992
|
+
<span class="code-block-title">app.pln</span>
|
|
1993
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
1994
|
+
</div>
|
|
1995
|
+
<pre><code><span class="kw">import</span> <span class="str">"./math.pln"</span>
|
|
1996
|
+
|
|
1997
|
+
<span class="kw">show</span> <span class="fn">add</span>(<span class="num">10</span>, <span class="num">20</span>)
|
|
1998
|
+
<span class="kw">show</span> <span class="fn">multiply</span>(<span class="num">6</span>, <span class="num">7</span>)</code></pre>
|
|
1999
|
+
</div>
|
|
2000
|
+
</div>
|
|
2001
|
+
</div>
|
|
2002
|
+
</section>
|
|
2003
|
+
|
|
2004
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
2005
|
+
<!-- ROADMAP -->
|
|
2006
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
2007
|
+
<section class="section section--alt" id="roadmap">
|
|
2008
|
+
<div class="container">
|
|
2009
|
+
<div class="section-tag"><i class="fa-solid fa-map"></i> Roadmap</div>
|
|
2010
|
+
<h2 class="section-title">What’s next</h2>
|
|
2011
|
+
<p class="section-lead">
|
|
2012
|
+
PlainScript 0.1.7 is the first release: one deterministic compiler, the complete language, production builds, backend services, and WhatsApp and Telegram bots. Here’s what’s planned next.
|
|
2013
|
+
</p>
|
|
2014
|
+
|
|
2015
|
+
<div class="roadmap">
|
|
2016
|
+
|
|
2017
|
+
<div class="roadmap-item">
|
|
2018
|
+
<div class="roadmap-version">0.1.7</div>
|
|
2019
|
+
<div class="roadmap-line-wrap">
|
|
2020
|
+
<div class="roadmap-dot done"></div>
|
|
2021
|
+
<div class="roadmap-connector"></div>
|
|
2022
|
+
</div>
|
|
2023
|
+
<div class="roadmap-content">
|
|
2024
|
+
<h4>0.1.7 — First release <span class="badge badge-green" style="margin-left:.5rem"><i class="fa-solid fa-check"></i> Released</span></h4>
|
|
2025
|
+
<ul>
|
|
2026
|
+
<li>Deterministic compiler — lexer, parser, generator and bundler with production builds to <code>dist/</code></li>
|
|
2027
|
+
<li>The complete language — conditions, functions, collections, string templates, PlainScript Expressions, multi-file projects and the JavaScript Gateway</li>
|
|
2028
|
+
<li>Backend services — routing, SQLite and PostgreSQL, sessions, password hashing and tokens, uploads, OCR, email, cron jobs, WebSocket servers and cache</li>
|
|
2029
|
+
<li>WhatsApp bots — QR and pairing-code linking; Telegram bots with inline keyboards</li>
|
|
2030
|
+
<li>Npm aliases and version ranges, interactive terminal input, formatter and doctor</li>
|
|
2031
|
+
</ul>
|
|
2032
|
+
</div>
|
|
2033
|
+
</div>
|
|
2034
|
+
|
|
2035
|
+
<div class="roadmap-item">
|
|
2036
|
+
<div class="roadmap-version">Future</div>
|
|
2037
|
+
<div class="roadmap-line-wrap">
|
|
2038
|
+
<div class="roadmap-dot"></div>
|
|
2039
|
+
</div>
|
|
2040
|
+
<div class="roadmap-content">
|
|
2041
|
+
<h4>Future — Extended Language <span class="badge badge-amber" style="margin-left:.5rem">Planned</span></h4>
|
|
2042
|
+
<ul>
|
|
2043
|
+
<li>Optional type hints (non-breaking)</li>
|
|
2044
|
+
<li><code>plainscript watch</code> — recompile on file change</li>
|
|
2045
|
+
<li>Language Server Protocol (LSP) support</li>
|
|
2046
|
+
<li>Standard library expansion & module refinements</li>
|
|
2047
|
+
</ul>
|
|
2048
|
+
</div>
|
|
2049
|
+
</div>
|
|
2050
|
+
|
|
2051
|
+
</div>
|
|
2052
|
+
</div>
|
|
2053
|
+
</section>
|
|
2054
|
+
|
|
2055
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
2056
|
+
<!-- FAQ -->
|
|
2057
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
2058
|
+
<section class="section" id="faq">
|
|
2059
|
+
<div class="container">
|
|
2060
|
+
<div class="section-tag"><i class="fa-solid fa-circle-question"></i> FAQ</div>
|
|
2061
|
+
<h2 class="section-title">Frequently Asked Questions</h2>
|
|
2062
|
+
|
|
2063
|
+
<div class="faq">
|
|
2064
|
+
|
|
2065
|
+
<div class="faq-item">
|
|
2066
|
+
<button class="faq-question">What is PlainScript? <i class="fa-solid fa-chevron-down"></i></button>
|
|
2067
|
+
<div class="faq-answer">
|
|
2068
|
+
PlainScript is an Intent-Oriented Programming Language (IOPL). It compiles <code>.pln</code> source files to JavaScript and runs them with Node.js. PlainScript’s design goal is to let developers describe <em>what</em> they want to happen in near-English sentences, while the compiler handles the JavaScript implementation details.
|
|
2069
|
+
</div>
|
|
2070
|
+
</div>
|
|
2071
|
+
|
|
2072
|
+
<div class="faq-item">
|
|
2073
|
+
<button class="faq-question">Is PlainScript production-ready? <i class="fa-solid fa-chevron-down"></i></button>
|
|
2074
|
+
<div class="faq-answer">
|
|
2075
|
+
PlainScript 0.1.7 includes runtime dependency detection, automatic installation, OCR, npm aliases and version ranges, portable databases, an HTTP client, sessions, uploads, rate limiting, deployment-oriented CLI commands, WhatsApp bots, and interactive terminal input — backed by a test suite of 625 checks. It compiles to standard Node.js-compatible JavaScript and remains well-suited for personal projects, tooling, and learning.
|
|
2076
|
+
</div>
|
|
2077
|
+
</div>
|
|
2078
|
+
|
|
2079
|
+
<div class="faq-item">
|
|
2080
|
+
<button class="faq-question">Does PlainScript support TypeScript? <i class="fa-solid fa-chevron-down"></i></button>
|
|
2081
|
+
<div class="faq-answer">
|
|
2082
|
+
Not yet. PlainScript compiles to plain JavaScript. Optional type hints are planned for a future version, but they will be designed to stay readable in PlainScript’s English-sentence style — not to mirror TypeScript syntax.
|
|
2083
|
+
</div>
|
|
2084
|
+
</div>
|
|
2085
|
+
|
|
2086
|
+
<div class="faq-item">
|
|
2087
|
+
<button class="faq-question">Can I use npm packages? <i class="fa-solid fa-chevron-down"></i></button>
|
|
2088
|
+
<div class="faq-answer">
|
|
2089
|
+
Yes. Any npm package can be declared with <code>use <package></code> and installed with <code>plainscript add <package></code>. Since v2.0.1 you can bind hyphenated or scoped packages to a variable with <code>use node-fetch as fetch</code>, and pin ranges inline with <code>use left-pad@^1.3.0</code>. PlainScript scans your source files for <code>use</code> declarations and manages the underlying <code>node_modules</code> automatically, validating that all declared packages are installed before compiling.
|
|
2090
|
+
</div>
|
|
2091
|
+
</div>
|
|
2092
|
+
|
|
2093
|
+
<div class="faq-item">
|
|
2094
|
+
<button class="faq-question">How does OCR work? <i class="fa-solid fa-chevron-down"></i></button>
|
|
2095
|
+
<div class="faq-answer">
|
|
2096
|
+
Write <code>ocr "scan.png" as text</code>. The statement is backed by Tesseract.js — an implementation detail that never appears in your source. <code>plainscript install</code>, <code>plainscript run</code>, and <code>plainscript build</code> detect <code>ocr</code> statements and fetch the package automatically. An optional <code>using "<lang>"</code> clause selects a language pack (<code>"deu"</code>, <code>"deu+eng"</code>, …); extraction defaults to English.
|
|
2097
|
+
</div>
|
|
2098
|
+
</div>
|
|
2099
|
+
|
|
2100
|
+
<div class="faq-item">
|
|
2101
|
+
<button class="faq-question">Can PlainScript build WhatsApp bots? <i class="fa-solid fa-chevron-down"></i></button>
|
|
2102
|
+
<div class="faq-answer">
|
|
2103
|
+
Yes. Write a <code>whatsapp bot</code> block with an <code>auth</code> folder and either <code>login qr</code>, <code>login pairing "<number>"</code>, or <code>login pairing phone</code> with the number typed in at runtime via <code>ask</code>. The first run links a real WhatsApp account by scanning the printed QR code or typing the pairing code into Linked Devices; later runs reconnect from saved credentials. Incoming messages flow through <code>on message ... done</code> handlers, and <code>reply</code> answers the current chat. Baileys is installed automatically — it never appears in your source.
|
|
2104
|
+
</div>
|
|
2105
|
+
</div>
|
|
2106
|
+
|
|
2107
|
+
<div class="faq-item">
|
|
2108
|
+
<button class="faq-question">What’s the difference between <code>for each</code> and <code>for every</code>? <i class="fa-solid fa-chevron-down"></i></button>
|
|
2109
|
+
<div class="faq-answer">
|
|
2110
|
+
They are identical. Both compile to a <code>for...of</code> JavaScript loop. <code>for every</code> is provided as an alias because it reads naturally in certain sentences — e.g. <em>for every item in basket</em>. In PlainScript, there is never a functional difference between the two.
|
|
2111
|
+
</div>
|
|
2112
|
+
</div>
|
|
2113
|
+
|
|
2114
|
+
<div class="faq-item">
|
|
2115
|
+
<button class="faq-question">How do I debug PlainScript code? <i class="fa-solid fa-chevron-down"></i></button>
|
|
2116
|
+
<div class="faq-answer">
|
|
2117
|
+
Use <code>plainscript build app.pln</code> to compile to <code>app.js</code> and inspect the generated JavaScript. Since the output is clean, readable JS you can open it in any Node.js debugger, add <code>console.log</code> statements, or run it directly with <code>node app.js</code>. You can also use <code>plainscript check app.pln</code> to catch syntax errors before running.
|
|
2118
|
+
</div>
|
|
2119
|
+
</div>
|
|
2120
|
+
|
|
2121
|
+
<div class="faq-item">
|
|
2122
|
+
<button class="faq-question">Does PlainScript work on Windows? <i class="fa-solid fa-chevron-down"></i></button>
|
|
2123
|
+
<div class="faq-answer">
|
|
2124
|
+
Yes. PlainScript is a Node.js package and works wherever Node.js is installed — Windows, macOS, and Linux. Install it with <code>npm install --save-dev plainscript</code> on any platform.
|
|
2125
|
+
</div>
|
|
2126
|
+
</div>
|
|
2127
|
+
|
|
2128
|
+
<div class="faq-item">
|
|
2129
|
+
<button class="faq-question">How do portable databases work? <i class="fa-solid fa-chevron-down"></i></button>
|
|
2130
|
+
<div class="faq-answer">
|
|
2131
|
+
Write <code>database "app.db"</code>. PlainScript probes the native driver (<code>better-sqlite3</code>) at startup and silently falls back to a pure-JavaScript WebAssembly engine (<code>sql.js</code>) if it is unavailable — same statements, same transactions, no code changes. Pin an engine explicitly with <code>using "native"</code> or <code>using "wasm"</code>; the WebAssembly engine persists the database file after every write so data survives restarts.
|
|
2132
|
+
</div>
|
|
2133
|
+
</div>
|
|
2134
|
+
|
|
2135
|
+
<div class="faq-item">
|
|
2136
|
+
<button class="faq-question">Is PlainScript’s compiler deterministic? <i class="fa-solid fa-chevron-down"></i></button>
|
|
2137
|
+
<div class="faq-answer">
|
|
2138
|
+
Yes. Every construct — including backend services like sessions, uploads, and OAuth — has explicit syntax and compiles to readable JavaScript through the fixed pipeline. No rules, no providers, no hidden code generation: what you read in <code>plainscript build</code> output is exactly what runs.
|
|
2139
|
+
</div>
|
|
2140
|
+
</div>
|
|
2141
|
+
|
|
2142
|
+
</div>
|
|
2143
|
+
</div>
|
|
2144
|
+
</section>
|
|
2145
|
+
|
|
2146
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
2147
|
+
<!-- CONTRIBUTING -->
|
|
2148
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
2149
|
+
<section class="section section--alt" id="contributing">
|
|
2150
|
+
<div class="container">
|
|
2151
|
+
<div class="section-tag"><i class="fa-solid fa-hands-helping"></i> Open Source</div>
|
|
2152
|
+
<h2 class="section-title">Contributing</h2>
|
|
2153
|
+
<p class="section-lead">
|
|
2154
|
+
PlainScript is open-source and welcomes contributions. Whether it’s a bug report, a test case, a documentation fix, or a new feature — every contribution matters.
|
|
2155
|
+
</p>
|
|
2156
|
+
|
|
2157
|
+
<div class="feature-grid" style="margin-bottom:2rem">
|
|
2158
|
+
<div class="feature-card">
|
|
2159
|
+
<div class="feature-card-icon"><i class="fa-solid fa-bug"></i></div>
|
|
2160
|
+
<h4>Report a bug</h4>
|
|
2161
|
+
<p>Found something that compiles incorrectly or crashes? Open an issue on GitHub with a minimal <code>.pln</code> reproduction.</p>
|
|
2162
|
+
</div>
|
|
2163
|
+
<div class="feature-card">
|
|
2164
|
+
<div class="feature-card-icon"><i class="fa-solid fa-flask"></i></div>
|
|
2165
|
+
<h4>Write a test</h4>
|
|
2166
|
+
<p>Tests live in <code>tests/compiler.test.js</code>. Adding a test for an edge case is one of the most valuable contributions.</p>
|
|
2167
|
+
</div>
|
|
2168
|
+
<div class="feature-card">
|
|
2169
|
+
<div class="feature-card-icon"><i class="fa-solid fa-code-pull-request"></i></div>
|
|
2170
|
+
<h4>Submit a pull request</h4>
|
|
2171
|
+
<p>Fork the repo, make your change, and run <code>node tests/compiler.test.js</code>. The full compiler and runtime suite must pass before merging.</p>
|
|
2172
|
+
</div>
|
|
2173
|
+
</div>
|
|
2174
|
+
|
|
2175
|
+
<div class="callout callout-info">
|
|
2176
|
+
<i class="fa-brands fa-github"></i>
|
|
2177
|
+
<div class="callout-body">
|
|
2178
|
+
<strong>GitHub repository</strong>
|
|
2179
|
+
<p>Source code, issues, and pull requests at <a href="https://github.com/ayoistooslick/plain-code" target="_blank" rel="noopener">github.com/ayoistooslick/plain-code</a>. Read <code>CONTRIBUTING.md</code> before opening a PR.</p>
|
|
2180
|
+
</div>
|
|
2181
|
+
</div>
|
|
2182
|
+
</div>
|
|
2183
|
+
</section>
|
|
2184
|
+
|
|
2185
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
2186
|
+
<!-- LICENSE -->
|
|
2187
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
2188
|
+
<section class="section" id="license">
|
|
2189
|
+
<div class="container">
|
|
2190
|
+
<div class="section-tag"><i class="fa-solid fa-scale-balanced"></i> License</div>
|
|
2191
|
+
<h2 class="section-title">MIT License</h2>
|
|
2192
|
+
<p style="color:var(--muted);max-width:640px;line-height:1.8">
|
|
2193
|
+
PlainScript is released under the <strong>MIT License</strong>. You are free to use, modify, and distribute PlainScript — commercially or non-commercially — with or without modification, as long as the original copyright notice is preserved.
|
|
2194
|
+
</p>
|
|
2195
|
+
|
|
2196
|
+
<div class="code-block" style="margin-top:1.5rem;max-width:640px">
|
|
2197
|
+
<div class="code-block-header">
|
|
2198
|
+
<div class="code-block-dots"><span></span><span></span><span></span></div>
|
|
2199
|
+
<span class="code-block-title">LICENSE</span>
|
|
2200
|
+
<button class="code-copy"><i class="fa-regular fa-copy"></i> Copy</button>
|
|
2201
|
+
</div>
|
|
2202
|
+
<pre><code>MIT License
|
|
2203
|
+
|
|
2204
|
+
Copyright (c) 2024 Ayokunle
|
|
2205
|
+
|
|
2206
|
+
Permission is hereby granted, free of charge, to any person
|
|
2207
|
+
obtaining a copy of this software and associated documentation
|
|
2208
|
+
files (the "Software"), to deal in the Software without
|
|
2209
|
+
restriction, including without limitation the rights to use,
|
|
2210
|
+
copy, modify, merge, publish, distribute, sublicense, and/or
|
|
2211
|
+
sell copies of the Software, and to permit persons to whom the
|
|
2212
|
+
Software is furnished to do so, subject to the following
|
|
2213
|
+
conditions:
|
|
2214
|
+
|
|
2215
|
+
The above copyright notice and this permission notice shall be
|
|
2216
|
+
included in all copies or substantial portions of the Software.
|
|
2217
|
+
|
|
2218
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.</code></pre>
|
|
2219
|
+
</div>
|
|
2220
|
+
</div>
|
|
2221
|
+
</section>
|
|
2222
|
+
|
|
2223
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
2224
|
+
<!-- FOOTER -->
|
|
2225
|
+
<!-- ════════════════════════════════════════════════════════════════════════ -->
|
|
2226
|
+
<footer class="site-footer">
|
|
2227
|
+
<div class="footer-inner">
|
|
2228
|
+
<div class="footer-brand">
|
|
2229
|
+
<span class="footer-logo"><span>PlainScript</span></span>
|
|
2230
|
+
<p>An Intent-Oriented Programming Language. Write programs in near-English. Compile to JavaScript.</p>
|
|
2231
|
+
<div class="footer-socials">
|
|
2232
|
+
<a href="https://github.com/ayoistooslick/plain-code" target="_blank" rel="noopener" aria-label="GitHub">
|
|
2233
|
+
<i class="fa-brands fa-github"></i>
|
|
2234
|
+
</a>
|
|
2235
|
+
<a href="https://www.npmjs.com/package/plainscript" target="_blank" rel="noopener" aria-label="npm">
|
|
2236
|
+
<i class="fa-brands fa-npm"></i>
|
|
2237
|
+
</a>
|
|
2238
|
+
</div>
|
|
2239
|
+
</div>
|
|
2240
|
+
|
|
2241
|
+
<div class="footer-col">
|
|
2242
|
+
<h5>Documentation</h5>
|
|
2243
|
+
<ul>
|
|
2244
|
+
<li><a href="#introduction">Introduction</a></li>
|
|
2245
|
+
<li><a href="#quickstart">Quick Start</a></li>
|
|
2246
|
+
<li><a href="#language">Language Reference</a></li>
|
|
2247
|
+
<li><a href="#examples">Examples</a></li>
|
|
2248
|
+
<li><a href="#packages">Packages</a></li>
|
|
2249
|
+
</ul>
|
|
2250
|
+
</div>
|
|
2251
|
+
|
|
2252
|
+
<div class="footer-col">
|
|
2253
|
+
<h5>Features</h5>
|
|
2254
|
+
<ul>
|
|
2255
|
+
<li><a href="#web">Web Development</a></li>
|
|
2256
|
+
<li><a href="#http">HTTP</a></li>
|
|
2257
|
+
<li><a href="#telegram">Telegram</a></li>
|
|
2258
|
+
<li><a href="#whatsapp">WhatsApp</a></li>
|
|
2259
|
+
<li><a href="#ocr">OCR</a></li>
|
|
2260
|
+
<li><a href="#database">Database</a></li>
|
|
2261
|
+
<li><a href="#cli">CLI Reference</a></li>
|
|
2262
|
+
</ul>
|
|
2263
|
+
</div>
|
|
2264
|
+
|
|
2265
|
+
<div class="footer-col">
|
|
2266
|
+
<h5>Project</h5>
|
|
2267
|
+
<ul>
|
|
2268
|
+
<li><a href="#backend-services">Backend Services</a></li>
|
|
2269
|
+
<li><a href="#security">Security</a></li>
|
|
2270
|
+
<li><a href="#roadmap">Roadmap</a></li>
|
|
2271
|
+
<li><a href="#faq">FAQ</a></li>
|
|
2272
|
+
<li><a href="#contributing">Contributing</a></li>
|
|
2273
|
+
</ul>
|
|
2274
|
+
</div>
|
|
2275
|
+
</div>
|
|
2276
|
+
|
|
2277
|
+
<div class="footer-bottom">
|
|
2278
|
+
<p>Copyright © 2026 Ayokunle. Released under the MIT License.</p>
|
|
2279
|
+
<span class="badge badge-blue version-badge">
|
|
2280
|
+
<i class="fa-solid fa-bolt"></i> PlainScript v0.1.7
|
|
2281
|
+
</span>
|
|
2282
|
+
</div>
|
|
2283
|
+
</footer>
|
|
2284
|
+
|
|
2285
|
+
<script src="website/script.js"></script>
|
|
2286
|
+
</body>
|
|
2287
|
+
</html>
|