swipl-wasm 1.2.0 → 3.0.0

package/README.md

@@ -14,63 +14,97 @@ In browser:
 <script>
   (async () => {
     const swipl = await SWIPL({
-      noInitialRun: true,
       arguments: ["-q"],
-      locateFile: (url) => {
-        if (url === "swipl-web.data") {
-          return "/dist/swipl/swipl-web.data";
-        } else if (url === "swipl-web.wasm") {
-          return "/dist/swipl/swipl-web.wasm";
-        }
-        return url;
+      locateFile: (path) => {
+        return `/dist/swipl/${path}`;
       },
     });
     const query = "member(X, [a, b, c]).";
     const solutionElement = document.getElementById("solution");
-    // See https://swi-prolog.discourse.group/t/swi-prolog-in-the-browser-using-wasm/5650/1
     const firstSolution = swipl.prolog.query(query).once().X;
     solutionElement.textContent = firstSolution;
   })();
 </script>
 ```
 
+The function `locateFile` will help the browser to find the necessary
+files (`swipl-web.wasm` and `swipl-web.data`). In this case the files
+should be served along with `swipl-web.js` under the `/dist/swipl`
+directory in the web server.
+
 You can run this example by executing `npm run test:serve-http` and
 visiting <http://localhost:8080/examples/browser.html>.
 
 In Nodejs:
 
 ```js
-// This helps to find the correct locations of the
-// .data and .wasm files.
-const swiplModuleLocation = require.resolve("swipl-wasm/swipl");
-const swipl = await SWIPL({
-  noInitialRun: true,
-  arguments: ["-q"],
-  locateFile: (url) => {
-    // These are common with the web version.
-    if (url === "swipl-web.data") {
-      return path.join(path.dirname(swiplModuleLocation), "swipl-web.data");
-    } else if (url === "swipl-web.wasm") {
-      return path.join(path.dirname(swiplModuleLocation), "swipl-web.wasm");
-    }
-    return url;
-  },
-});
-// See https://swi-prolog.discourse.group/t/swi-prolog-in-the-browser-using-wasm/5650/1
+const swipl = await SWIPL({ arguments: ["-q"] });
 console.log(swipl.prolog.query("member(X, [a, b, c]).").once().X);
 ```
 
 You can run this example with `node examples/run-on-node.js`.
 
+## Running JavaScript from Prolog
+
+This uses `eval`:
+
+```js
+swipl.prolog
+  .query("js_run_script(Script)", {
+    Script: `console.log('hello')`,
+  })
+  .once();
+```
+
+## Using with Webpack
+
+[Webpack](https://webpack.js.org/) is a JavaScript and resources
+bundler for large-scale frontend projects.
+
+There is an example Webpack project in `examples/webpack`. It uses
+[Asset Modules](https://webpack.js.org/guides/asset-modules/) to "load"
+necessary `.data` and `.wasm` files. The location of these files and then
+fed to `locateFile` (see above).
+
+The package `swipl-wasm` is linked into the example. In an actual project
+you would declare `swipl-wasm` as a normal dependency.
+
+To start the example:
+
+```
+cd examples/webpack
+npm install
+npm build
+npm run server
+```
+
+and visit <http://127.0.0.1:8080>. You should see the message "Hello world from
+Prolog".
+
 ## Build
 
 The package can be built using npm or yarn. Please use yarn to
 add new dependencies and update yarn.lock file. SWI-Prolog WebAssembly
 version is currently built inside Docker with Emscripten.
 
+## Versioning
+
+The package uses its own versioning scheme using semver. It is
+detached from the versioning of SWI-Prolog itself.
+
+To get the underlying SWI-Prolog version:
+
+```js
+const swipl = await SWIPL({ arguments: ["-q"] });
+const version = swipl.prolog
+  .query("current_prolog_flag(version, Version)")
+  .once().Version;
+```
+
+The version is returned as integer `10000 × Major + 100 × Minor + Patch`.
+
 ## TODO
 
-- More examples (how to bundle with webpack)
 - Integrate with SWI-Prolog CI
 - TypeScript types for Prolog.js (and the Query interface)
 - Use EcmaScript modules as output:

package/dist/common.d.ts

@@ -0,0 +1,88 @@
+/// <reference types="emscripten" />
+
+type CallOptions = {
+  /**
+   * Module in which to call Goal.
+   */
+  module?: string;
+  /**
+   * Call as yieldable.
+   */
+  async?: boolean;
+};
+
+/**
+ * Query interface for opening new queries.
+ */
+type Query = {
+  /**
+   * Fetches the next solution.
+   */
+  next(): unknown;
+  /**
+   * Runs the query. If there is a solution then returns it.
+   * Closes the query.
+   */
+  once(): unknown;
+};
+
+/**
+ * Prolog-JavaScript interface of the Prolog instance.
+ */
+type Prolog = {
+  /**
+   * Call a Prolog goal.  This function deals with munknown variations to
+   * call Prolog.
+   */
+  call(goal: string, opts?: CallOptions): unknown;
+
+  /**
+   * Run a possibly long running goal and process its answers.
+   *
+   * @param goal Goal to run.
+   * @param input Goal input.
+   * @param callback Optional callback to process.
+   * @return A promise that is resolved on completion and rejected on
+   * a Prolog exception.
+   */
+  forEach(
+    goal: string,
+    input?: unknown,
+    callback?: (prolog: Prolog, answer: unknown) => void
+  ): Promise<unknown>;
+
+  /**
+   * Calls the goal while binding input arguments.
+   *
+   * @param goal Goal to run.
+   * @param input Input variable bindings.
+   */
+  query(goal: string, input?: Record<string, unknown>): Query;
+};
+
+/**
+ * SWI-Prolog instance.
+ */
+type SWIPLModule = {
+  /**
+   * Emscripten emulated file system interface.
+   */
+  FS: typeof FS;
+  /**
+   * Prolog interface.
+   */
+  prolog: Prolog;
+};
+
+declare namespace initSWIPL {
+  export { SWIPLModule, Prolog, Query };
+}
+
+/**
+ * Factory function that creates a SWI-Prolog instance.
+ */
+declare function initSWIPL(
+  options?: Partial<EmscriptenModule>
+): Promise<SWIPLModule>;
+
+export = initSWIPL;

package/dist/swipl/swipl-web.d.ts

@@ -0,0 +1,2 @@
+import SWIPL = require("../common");
+export = SWIPL;