feat: new class-based API

The new API exposes pioasm errors and exit code. It also enables the creation of multiple pioasm instances.

Author: urish

README.md

@@ -25,16 +25,17 @@ yarn add pioasm
 Usage example:
 
 ```javascript
-import { pioasm } from 'pioasm';
+import { PIOAssembler } from 'pioasm';
 
 const source = `
   .program blink
   pull block
   out y, 32
 `;
 
-pioasm(source).then(result => {
-  console.log(result);
+const pioasm = new PIOAssembler();
+pioasm.assemble(source).then(result => {
+  console.log(result.output);
 })
 ```
 

pioasm.js

@@ -6,9 +6,6 @@
 
 import wasm from '#pioasm-emcc';
 
-let instance = null;
-let outputBuffer = [];
-
 /**
  * PIO Output format:
  * - c-sdk: C header suitable for use with the Raspberry Pi Pico SDK
@@ -20,46 +17,70 @@ let outputBuffer = [];
  */
 
 /**
- * Loads the pioasm Web Assembly module. Normally, `pioasm()` will load the module for
- * you, but you can use the `load()` method to pre-loader the Web Assembly module, or
- * if you need to provide custom options to EMScripten.
- *
- * For instance, you can override the `locateFile(url: string, scriptDirectory: string)`
- * method to configure the URL for the compiled web assembly module.
- *
- * @param {Partial<EmscriptenModule>} [options]
- * @returns {Promise<EmscriptenModule>}
+ * PIO Assembler wrapper class
  */
-export async function load(options) {
-  if (!instance) {
-    instance = wasm({
-      noInitialRun: true,
-      print(msg) {
-        outputBuffer.push(msg);
-      },
-      ...options,
-    });
+export class PIOAssembler {
+  /** @private */
+  exitCode = 0;
+  /** @private */
+  outputBuffer = [];
+  /** @private */
+  instance;
+
+  constructor() {}
+
+  /**
+   * Loads the pioasm Web Assembly module. Normally, `pioasm()` will load the module for
+   * you, but you can use the `load()` method to pre-loader the Web Assembly module, or
+   * if you need to provide custom options to EMScripten.
+   *
+   * For instance, you can override the `locateFile(url: string, scriptDirectory: string)`
+   * method to configure the URL for the compiled web assembly module.
+   *
+   * @param {Partial<EmscriptenModule>} [options]
+   * @returns {Promise<EmscriptenModule>}
+   */
+  async load(options) {
+    if (!this.instance) {
+      this.instance = wasm({
+        noInitialRun: true,
+        print: (msg) => {
+          this.outputBuffer.push(msg);
+        },
+        printErr: (msg) => {
+          this.outputBuffer.push(msg);
+        },
+        quit: (code) => {
+          this.exitCode = code;
+        },
+        ...options,
+      });
+    }
+    return this.instance;
   }
-  return await instance;
-}
 
-/**
- * Compiles the given PIO source file.
- *
- * @param {string} source PIO source to compile
- * @param {PioOutputFormat} [format='c-sdk'] Output format
- * @param {string} [outputParam] Add a parameter to be passed to the output format generator
- * @returns Promise<String>
- */
-export async function pioasm(source, format = 'c-sdk', outputParam) {
-  const runtime = await load();
-  runtime.FS_writeFile('/input.pio', source);
-  outputBuffer = [];
-  const argv = ['-o', format];
-  if (outputParam) {
-    argv.push('-p', outputParam);
+  /**
+   * Compiles the given PIO source file.
+   *
+   * @param {string} source PIO source to compile
+   * @param {PioOutputFormat} [format='c-sdk'] Output format
+   * @param {string} [outputParam] Add a parameter to be passed to the output format generator
+   * @returns Promise<{output: string, exitCode: number}>
+   */
+  async assemble(source, format = 'c-sdk', outputParam) {
+    const runtime = await this.load();
+    runtime.FS_writeFile('/input.pio', source);
+    this.outputBuffer = [];
+    this.exitCode = 0;
+    const argv = ['-o', format];
+    if (outputParam) {
+      argv.push('-p', outputParam);
+    }
+    argv.push('input.pio');
+    runtime.callMain(argv);
+    return {
+      output: this.outputBuffer.join('\n'),
+      exitCode: this.exitCode,
+    };
   }
-  argv.push('input.pio');
-  runtime.callMain(argv);
-  return outputBuffer.join('\n');
 }

prettier.config.js renamed to prettier.config.cjs

@@ -3,7 +3,7 @@
  */
 
 import assert from 'assert';
-import { pioasm } from './pioasm.js';
+import { PIOAssembler } from './pioasm.js';
 
 const testInput = `
   .program blink
@@ -30,9 +30,31 @@ def blink():
 
 `;
 
+const badProgram = `
+.program bad
+  jmp unknown
+`;
+
 async function main() {
-  assert.strictEqual(await pioasm(testInput, 'python'), expectedOutput);
-  assert.strictEqual(await pioasm(testInput, 'hex'), '80a0\n6040');
+  const pioasm = new PIOAssembler();
+
+  assert.deepStrictEqual(await pioasm.assemble(testInput, 'python'), {
+    output: expectedOutput,
+    exitCode: 0,
+  });
+
+  assert.deepStrictEqual(await pioasm.assemble(testInput, 'hex'), {
+    output: '80a0\n6040',
+    exitCode: 0,
+  });
+
+  assert.deepStrictEqual(await pioasm.assemble(badProgram, 'c-sdk'), {
+    output: `input.pio:3.7-13: undefined symbol 'unknown'
+    3 |   jmp unknown
+      |       ^~~~~~~`,
+    exitCode: 1,
+  });
+
   console.log('Test passed successfully!');
 }