@lucy/liblucy 0.5.5 → 0.6.0

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/dist/lucy.wasm ADDED
Binary file
package/liblucy.d.ts CHANGED
@@ -1,11 +1,50 @@
1
1
  declare namespace LibLucy {
2
- interface CompileXStateOptions {
3
- useRemote: boolean;
2
+ interface CompileOptions {
3
+ /** Also produce TypeScript declarations (.d.ts) for the module. Experimental. */
4
+ dts?: boolean;
4
5
  }
5
6
 
7
+ interface CompileResult {
8
+ /** The compiled JavaScript module. */
9
+ js: string;
10
+ /** The module's TypeScript declarations, when the `dts` option is set. */
11
+ dts?: string;
12
+ }
13
+
14
+ /** An error or warning from the compiler. */
15
+ interface Diagnostic {
16
+ severity: 'error' | 'warning';
17
+ /** The message alone, such as 'Unexpected identifier'. */
18
+ message: string;
19
+ /** The line (counting from 1) of an error. 0 for warnings. */
20
+ line: number;
21
+ /** The column of an error. 0 for warnings. */
22
+ column: number;
23
+ /** The diagnostic as lucyc prints it, with ANSI colours. */
24
+ text: string;
25
+ }
26
+
27
+ /** What compile throws when the source doesn't compile. */
28
+ interface CompileError extends Error {
29
+ message: 'Compiler error';
30
+ /** The errors and warnings, in the order the compiler reported them. */
31
+ diagnostics: Diagnostic[];
32
+ }
33
+
34
+ /** Resolves when dist/lucy.wasm is loaded and compile can be called. */
6
35
  export const ready: Promise<void>;
7
36
 
8
- export function compileXstate(source: string, filename: string, options?: CompileXStateOptions): string;
37
+ /**
38
+ * Compile Lucy source to a JavaScript module of plain state machines: one
39
+ * exported factory per machine, which returns a machine with `state`,
40
+ * `context`, `send`, `subscribe`, `start` and `stop`.
41
+ *
42
+ * Prints the compile's errors and warnings to the console as lucyc does:
43
+ * errors with console.error, warnings with console.log, one call each.
44
+ * Throws a CompileError if the source doesn't compile, after printing
45
+ * them.
46
+ */
47
+ export function compile(source: string, filename: string, options?: CompileOptions): CompileResult;
9
48
  }
10
49
 
11
50
  export = LibLucy;
package/liblucy.mjs CHANGED
@@ -1,77 +1,160 @@
1
- //import createModule from './dist/liblucy-debug.mjs';
1
+ // The JavaScript side of dist/lucy.wasm: compile() on top of the C API in
2
+ // src/core/lucy.h. main-node.mjs and main-browser.js load the module and
3
+ // pass its instance here.
4
+ //
5
+ // The module imports nothing and exports its memory, malloc and free, and
6
+ // the lucy_* functions. Strings cross as NUL-terminated UTF-8 in that
7
+ // memory. It grows when malloc needs more, which replaces memory.buffer,
8
+ // so views of it are made fresh after every call into the module.
2
9
 
3
- export default async function(createModule) {
4
- const moduleReady = createModule();
5
- const Module = await moduleReady;
10
+ const encoder = new TextEncoder();
11
+ const decoder = new TextDecoder();
6
12
 
7
- const {
8
- stackAlloc,
9
- stackRestore,
10
- stackSave,
11
- stringToUTF8,
12
- UTF8ToString
13
- } = Module;
13
+ /**
14
+ * @param instance {WebAssembly.Instance} an instance of dist/lucy.wasm.
15
+ * @param options {{ print?: (text: string) => void, printErr?: (text: string) => void }}
16
+ * where compile prints diagnostics: lucyc's stdout and stderr, by
17
+ * default console.log and console.error.
18
+ * @returns the compile function.
19
+ */
20
+ export function createCompiler(instance, {
21
+ print = console.log,
22
+ printErr = console.error
23
+ } = {}) {
24
+ const wasm = instance.exports;
25
+ // A reactor module's constructors run in _initialize, once, before any
26
+ // other call. lucy.wasm has none today, but that could change.
27
+ wasm._initialize?.();
14
28
 
15
- const _compileXstate = Module._compile_xstate;
16
- const _xsGetJS = Module._xs_get_js;
17
- const _xsGetDTS = Module._xs_get_dts;
18
- const _xsCreate = Module._xs_create;
19
- const _xsInit = Module._xs_init;
20
- const _destroyXstateResult = Module._destroy_xstate_result;
29
+ // The module's memory as bytes. Make a new view after every call into the
30
+ // module: if the memory grew, the old one is empty.
31
+ function bytes() {
32
+ return new Uint8Array(wasm.memory.buffer);
33
+ }
21
34
 
22
- function stringToPtr(str) {
23
- var ret = 0;
24
- if (str !== null && str !== undefined && str !== 0) { // null string
25
- // at most 4 bytes per UTF-8 code point, +1 for the trailing '\0'
26
- var len = (str.length << 2) + 1;
27
- ret = stackAlloc(len);
28
- stringToUTF8(str, ret, len);
35
+ // A NUL-terminated UTF-8 copy of str in the module's memory, which the
36
+ // caller must free.
37
+ function writeString(str) {
38
+ const encoded = encoder.encode(str);
39
+ // Pointers come back as signed 32-bit numbers; >>> 0 keeps one above
40
+ // 2 GB positive.
41
+ const ptr = wasm.malloc(encoded.length + 1) >>> 0;
42
+ // malloc returns 0 when the memory can't grow enough. Writing the
43
+ // string there would overwrite the start of memory.
44
+ if(ptr === 0) {
45
+ throw new Error('Out of memory');
46
+ }
47
+ const heap = bytes();
48
+ heap.set(encoded, ptr);
49
+ heap[ptr + encoded.length] = 0;
50
+ return ptr;
51
+ }
52
+
53
+ // The NUL-terminated string at ptr. NULL reads as ''.
54
+ function readString(ptr) {
55
+ ptr >>>= 0;
56
+ if(ptr === 0) {
57
+ return '';
58
+ }
59
+ const heap = bytes();
60
+ return decoder.decode(heap.subarray(ptr, heap.indexOf(0, ptr)));
61
+ }
62
+
63
+ // The result's errors and warnings, as plain objects.
64
+ function readDiagnostics(result) {
65
+ const diagnostics = [];
66
+ const count = wasm.lucy_result_diagnostic_count(result) >>> 0;
67
+ for(let i = 0; i < count; i++) {
68
+ const diagnostic = wasm.lucy_result_diagnostic(result, i);
69
+ diagnostics.push({
70
+ severity: wasm.lucy_diagnostic_severity(diagnostic) === 0 ? 'error' : 'warning',
71
+ message: readString(wasm.lucy_diagnostic_message(diagnostic)),
72
+ line: wasm.lucy_diagnostic_line(diagnostic),
73
+ column: wasm.lucy_diagnostic_column(diagnostic),
74
+ text: readString(wasm.lucy_diagnostic_text(diagnostic))
75
+ });
76
+ }
77
+ return diagnostics;
78
+ }
79
+
80
+ // Print the result's errors and warnings as lucyc does: errors to
81
+ // printErr, and the warnings lucyc prints to stdout to print. The text
82
+ // ends in a newline, which console.log and console.error add themselves.
83
+ function printDiagnostics(result) {
84
+ const count = wasm.lucy_result_diagnostic_count(result) >>> 0;
85
+ for(let i = 0; i < count; i++) {
86
+ const diagnostic = wasm.lucy_result_diagnostic(result, i);
87
+ const text = readString(wasm.lucy_diagnostic_text(diagnostic));
88
+ // 1 is LUCY_STREAM_STDOUT.
89
+ const write = wasm.lucy_diagnostic_stream(diagnostic) === 1 ? print : printErr;
90
+ write(text.endsWith('\n') ? text.slice(0, -1) : text);
29
91
  }
30
- return ret;
31
92
  }
32
93
 
33
94
  /**
34
- * Compile Lucy source a module of XState machines.
95
+ * Compile Lucy source to a module of plain JavaScript state machines.
35
96
  * @param source {String} the input Lucy source.
36
97
  * @param filename {String} the name of the Lucy file.
37
- * @param options {Object}
38
- * @returns {String} The compiled JavaScript module.
98
+ * @param options {{ dts?: boolean }}
99
+ * @returns {{ js: string, dts?: string }} The compiled JavaScript module,
100
+ * and its TypeScript declarations if options.dts is set.
101
+ * @throws {Error} 'Compiler error' if the source doesn't compile, with the
102
+ * errors and warnings in its diagnostics property.
39
103
  */
40
- function compileXstate(source, filename, options = {
41
- useRemote: false
42
- }) {
104
+ function compile(source, filename, options = {}) {
43
105
  if(!source || !filename) {
44
106
  throw new Error('Source and filename are both required.');
45
107
  }
46
-
47
- let stack = stackSave();
48
- let srcPtr = stringToPtr(source);
49
- let fnPtr = stringToPtr(filename);
50
- let resPtr = _xsCreate();
51
- _xsInit(resPtr, options.useRemote, options.dts);
52
- _compileXstate(resPtr, srcPtr, fnPtr);
53
- stackRestore(stack);
54
-
55
- const HEAPU8 = Module.HEAPU8;
56
- let success = !!HEAPU8[resPtr];
57
-
58
- if(success) {
59
- let out = {};
60
- let jsPtr = _xsGetJS(resPtr);
61
- out.js = UTF8ToString(jsPtr);
62
- if(options.dts) {
63
- let dtsPtr = _xsGetDTS(resPtr);
64
- out.dts = UTF8ToString(dtsPtr);
108
+
109
+ // Read the options before allocating anything, so that bad options
110
+ // can't throw with memory still allocated.
111
+ const dts = options.dts;
112
+
113
+ const srcPtr = writeString(source);
114
+ let fnPtr;
115
+ try {
116
+ fnPtr = writeString(filename);
117
+ } catch(err) {
118
+ wasm.free(srcPtr);
119
+ throw err;
120
+ }
121
+ let result = 0;
122
+ let out = null;
123
+ let diagnostics = null;
124
+ try {
125
+ result = wasm.lucy_result_create();
126
+ // dts becomes an i32 as it always has (true is 1, undefined 0), while
127
+ // whether out.dts is set follows its truthiness, as before.
128
+ wasm.lucy_result_set_options(result, dts);
129
+ wasm.lucy_compile(result, srcPtr, fnPtr);
130
+
131
+ // The compiler doesn't print; this prints what lucyc would.
132
+ printDiagnostics(result);
133
+
134
+ if(wasm.lucy_result_success(result)) {
135
+ out = {};
136
+ out.js = readString(wasm.lucy_result_js(result));
137
+ if(dts) {
138
+ out.dts = readString(wasm.lucy_result_dts(result));
139
+ }
140
+ } else {
141
+ diagnostics = readDiagnostics(result);
65
142
  }
66
- _destroyXstateResult(resPtr);
67
- return out;
143
+ } finally {
144
+ // Free everything, even if the module trapped. Destroying NULL does
145
+ // nothing.
146
+ wasm.lucy_result_destroy(result);
147
+ wasm.free(fnPtr);
148
+ wasm.free(srcPtr);
149
+ }
150
+
151
+ if(out === null) {
152
+ const err = new Error('Compiler error');
153
+ err.diagnostics = diagnostics;
154
+ throw err;
68
155
  }
69
-
70
- let err = new Error('Compiler error');
71
- throw err;
156
+ return out;
72
157
  }
73
158
 
74
- return {
75
- compileXstate
76
- };
77
- }
159
+ return compile;
160
+ }
@@ -0,0 +1,25 @@
1
+ // liblucy for browsers (and bundlers, which recognise the new URL(...,
2
+ // import.meta.url) below): fetches dist/lucy.wasm next to this file.
3
+ import { createCompiler } from './liblucy.mjs';
4
+
5
+ const url = new URL('./dist/lucy.wasm', import.meta.url);
6
+
7
+ async function instantiate() {
8
+ const response = await fetch(url);
9
+ if(!response.ok) {
10
+ throw new Error(`Couldn't fetch ${url}: ${response.status}`);
11
+ }
12
+ // Streaming compiles while the bytes download, but only works when the
13
+ // server sends the file as application/wasm.
14
+ if(WebAssembly.instantiateStreaming &&
15
+ response.headers.get('Content-Type') === 'application/wasm') {
16
+ return (await WebAssembly.instantiateStreaming(response)).instance;
17
+ }
18
+ return (await WebAssembly.instantiate(await response.arrayBuffer())).instance;
19
+ }
20
+
21
+ export let compile;
22
+
23
+ export let ready = instantiate().then(instance => {
24
+ compile = createCompiler(instance);
25
+ });
package/main-node.mjs ADDED
@@ -0,0 +1,11 @@
1
+ // liblucy for Node.js: loads dist/lucy.wasm from disk.
2
+ import { readFile } from 'node:fs/promises';
3
+ import { createCompiler } from './liblucy.mjs';
4
+
5
+ export let compile;
6
+
7
+ export let ready = readFile(new URL('./dist/lucy.wasm', import.meta.url))
8
+ .then(bytes => WebAssembly.instantiate(bytes))
9
+ .then(({ instance }) => {
10
+ compile = createCompiler(instance);
11
+ });
package/package.json CHANGED
@@ -1,37 +1,27 @@
1
1
  {
2
2
  "name": "@lucy/liblucy",
3
- "version": "0.5.5",
3
+ "version": "0.6.0",
4
4
  "description": "The Lucy compiler project.",
5
5
  "exports": {
6
6
  ".": {
7
- "node": {
8
- "development": "./main-node-dev.mjs",
9
- "production": "./main-node-prod.mjs",
10
- "import": "./main-node-prod.mjs"
11
- },
12
- "browser": {
13
- "development": "./main-browser-dev.js",
14
- "production": "./main-browser-prod.js",
15
- "import": "./main-browser-prod.js"
16
- }
7
+ "node": "./main-node.mjs",
8
+ "browser": "./main-browser.js"
17
9
  }
18
10
  },
19
11
  "types": "./liblucy.d.ts",
20
12
  "files": [
21
- "dist",
13
+ "dist/lucy.wasm",
22
14
  "liblucy.mjs",
23
15
  "liblucy.d.ts",
24
- "main-node-dev.mjs",
25
- "main-node-prod.mjs",
26
- "main-browser-dev.js",
27
- "main-browser-prod.js"
16
+ "main-node.mjs",
17
+ "main-browser.js"
28
18
  ],
29
19
  "scripts": {
30
20
  "test": "make test"
31
21
  },
32
22
  "repository": {
33
23
  "type": "git",
34
- "url": "git+https://github.com/matthewp/liblucy.git"
24
+ "url": "git+https://github.com/lucydsl/liblucy.git"
35
25
  },
36
26
  "keywords": [
37
27
  "Lucy",
@@ -41,7 +31,7 @@
41
31
  "author": "Matthew Phillips <matthew@matthewphillips.info>",
42
32
  "license": "BSD-2-Clause",
43
33
  "bugs": {
44
- "url": "https://github.com/matthewp/liblucy/issues"
34
+ "url": "https://github.com/lucydsl/liblucy/issues"
45
35
  },
46
- "homepage": "https://github.com/matthewp/liblucy#readme"
36
+ "homepage": "https://github.com/lucydsl/liblucy#readme"
47
37
  }
package/readme.md CHANGED
@@ -1,11 +1,75 @@
1
1
  # liblucy
2
2
 
3
- __liblucy__ is the core piece of [Lucy](https://lucylang.org/) the DSL. It contains the core compiler that is compiled to wasm for usage in JavaScript environments such as Node.js. It also includes the CLI compiler, `lucyc`.
3
+ __liblucy__ is the core piece of [Lucy](https://lucy.spooky.click/) the DSL. It contains the core compiler that is compiled to wasm for usage in JavaScript environments such as Node.js. It also includes the CLI compiler, `lucyc`.
4
+
5
+ ## Output
6
+
7
+ The compiler turns a Lucy file into a module of plain JavaScript state machines, with no runtime library: one exported factory per machine (`createLight` for `machine light`, a default export for the file's unnamed machine), each a small set of ordinary functions for just what that machine does.
8
+
9
+ ```js
10
+ import createMachine from './toggle.js';
11
+
12
+ const machine = createMachine({ context: { count: 0 } });
13
+ machine.subscribe(m => render(m.state, m.context));
14
+ machine.start();
15
+ machine.send('toggle');
16
+ machine.send({ type: 'set', data: 5 });
17
+ console.log(machine.state, machine.context);
18
+ machine.stop();
19
+ ```
20
+
21
+ - `createMachine({ context, actions, guards, assigns, delays, services })`: the options supply what the Lucy source names with `:symbols`, each called as `(context, event)`; a `services` entry returns a promise for `invoke(:name)` and an unstarted machine for `spawn(:name)`. Only the options a machine uses are read.
22
+ - `state` is the current state's name, or a dotted path such as `'red.walk'` inside a nested machine. `context` is a plain object, replaced (not mutated) by each `assign`. `done` becomes `true` when a final state is entered.
23
+ - `send(event)` takes a type or an `{ type, data }` object and runs the transition at once. `subscribe(listener)` calls the listener with the machine after each change and returns an unsubscribe function. `start()` enters the initial state (entry actions, timers, invokes) and returns the machine; `stop()` clears timers, drops pending invokes, stops invoked and spawned children, and clears the listeners.
24
+ - `--experimental-dts` writes a `.d.ts` that types each factory's options and the machine it returns.
25
+
26
+ ## Typed events
27
+
28
+ A machine can declare its events, and the type of the data each carries:
29
+
30
+ ```lucy
31
+ use './types' { User }
32
+
33
+ machine session {
34
+ event login(User)
35
+ event rename(string)
36
+ event logout
37
+
38
+ initial state anonymous {
39
+ login => assign(user) => active
40
+ }
41
+
42
+ state active {
43
+ rename => assign(name)
44
+ logout => anonymous
45
+ }
46
+ }
47
+ ```
48
+
49
+ - A type is a single name: one imported with `use`, or one TypeScript already knows (`string`, `number`, `MouseEvent`). Give any other type (`string[]`, a union) a name in a `.ts` file and import it. A name used as an event's type is imported as a type only: the JavaScript leaves it out and the `.d.ts` has `import type`.
50
+ - The type is that of the event's `data`: `machine.send({ type: 'login', data: user })`.
51
+ - Events are declared in a top-level `machine { }` block, for that machine and the machines nested in its states. An event has one type, whichever state handles it.
52
+ - The declarations change nothing in the JavaScript. The compiler warns about a transition on an event the machine doesn't declare, a declared event no state handles, `assign(key)` on an event declared without data, and `send(child, event)` to a machine spawned from the same file that doesn't declare `event`. A machine that declares no events is not checked.
53
+ - In the `.d.ts`, the machine's events become `SessionEvents` (by name, so `SessionEvents['login']` types the event parameter of an imported guard or action) and their union `SessionEvent`. `send` takes a `SessionEvent`, or the name alone for an event without data. What the options supply is typed with the events it is used on, and the `context` passed in has to be able to hold the data that `assign(key)` stores.
4
54
 
5
55
  ## Contributing
6
56
 
7
- See the [contributing page](https://lucylang.org/docs/contributing/) for information on how to build liblucy and the workflow for making changes.
57
+ See the [contributing page](https://lucy.spooky.click/docs/contributing/) for information on how to build liblucy and the workflow for making changes.
8
58
 
9
59
  ## License
10
60
 
11
- BSD-2-Clause
61
+ BSD-2-Clause
62
+ ## Building
63
+
64
+ The wasm module, `dist/lucy.wasm`, is built with clang from [wasi-sdk](https://github.com/WebAssembly/wasi-sdk), statically linking wasi-libc. It imports nothing, and `liblucy.mjs` drives it through the standard WebAssembly API, with `main-node.mjs` and `main-browser.js` loading it. `scripts/get_wasi_sdk` downloads the pinned wasi-sdk release into `~/.cache/wasi-sdk`, where the Makefile looks for it (set `WASI_SDK` to use another copy):
65
+
66
+ ```sh
67
+ scripts/get_wasi_sdk
68
+ make all
69
+ ```
70
+
71
+ The native compiler, `bin/lucyc`, only needs a C17 compiler: `make bin/lucyc`. Run the tests with `make test`. The code builds without warnings under the strict set in the Makefile; `make WERROR=1 ...` makes them errors, as CI does.
72
+
73
+ `src/README.md` describes how the sources are laid out and the conventions they follow.
74
+
75
+ `make test-sanitize` checks for memory errors and leaks: it runs the tests, and every `.lucy` file under `test/`, through native builds with AddressSanitizer and UndefinedBehaviorSanitizer. It needs GCC or Clang on Linux.