hs2js v0.0.9

hs2js

Experimental haskell in javascript interpreter. Many haskell features are not implemented. This projects mainly exists to be able to write and interpret Tidal Cycles code in the browser, as part of Strudel. This project could only exist thanks to tree-sitter-haskell.

Installation

Via Script Tag

You can load the library directly from a script tag via unpkg:

<script src="https://unpkg.com/hs2js@0.0.3"></script>
<button id="hello">hello</button>
<script>
  hs2js.setBase('https://unpkg.com/hs2js@0.0.3/dist/');
  hs2js.loadParser().then(()=>{
    document.getElementById('hello').addEventListener('click', () => {
      hs2js.evaluate('alert "hello from haskell!"');
    });
  })
</script>

Via npm

You need to add postinstall to your package.json script to copy the parser to your public folder:

{
  "scripts": {
    "postinstall": "cp node_modules/hs2js/dist/tree-sitter.wasm public && cp node_modules/hs2js/dist/tree-sitter-haskell.wasm public"
  }
}

Depending on your setup, replace public with the folder that will serve your assets to /. Then install the package:

npm i hs2js

and use it:

import * as hs2js from 'hs2js';
hs2js.loadParser();
document.getElementById('hello').addEventListener('click', () => {
  hs2js.evaluate('alert "hello from haskell!"');
});

API

These are all functions exported by the package:

evaluate

Evaluates a piece of haskell code

• code: valid haskell code
• scope: global scope, defaults to globalThis. Allows you to pass an object of your own functions / variables from JS to Haskell.
• ops: mapping for custom infix operator

Example:

// simple
hs2js.evaluate(`2 + 2`) // = 4
// passing variables via scope:
hs2js.evaluate(`a + b`, { a: 1, b: 2 }) // = 3
// custom operator
hs2js.evaluate(`2 |* 3`, {}, { '|*': (l, r) => l * r }) // = 6

parse

Parses a piece of haskell code, returning its AST representation.

Example:

const ast = hs2js.parse(`2 + 2`)
console.log(ast.toString())
// (haskell declarations: (declarations (top_splice (apply function: (variable) argument: (literal (integer))))))

run

Evaluates rootNode of haskell AST (used by evaluate internally).

• rootNode: haskell AST root node, as returned by parse
• scope: see evaluate
• ops: see evaluate

Example:

const ast = hs2js.parse(`2 + 3`);
const res = hs2js.run(ast.rootNode);
console.log(res); // = 5

loadParser

Loads and caches the parser by fetching tree-sitter.wasm and tree-sitter-haskell.wasm. Make sure to call and await this function before calling parse or evaluate.

hs2js.loadParser().then(() => hs2js.evaluate('alert "ready"'))

setBase

Sets the base path where the WASM files are expected by loadParser. Defaults to /. Expects tree-sitter.wasm and tree-sitter-haskell.wasm to be present. Can either be a relative path or a URL.

hs2js.setBase('https://unpkg.com/hs2js@0.0.4/dist/');
hs2js.loadParser(); 
/* loads 
- https://unpkg.com/hs2js@0.0.4/dist/tree-sitter.wasm
- https://unpkg.com/hs2js@0.0.4/dist/tree-sitter-haskell.wasm
*/