# 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](https://tidalcycles.org/) code in the browser,

as part of [Strudel](https://codeberg.org/uzu/strudel). This project could only exist thanks to [tree-sitter-haskell](https://github.com/tree-sitter/tree-sitter-haskell).

## Installation

### Via Script Tag

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

```html

<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:

```json

{

  "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:

```sh

npm i hs2js

```

and use it:

```js

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](https://github.com/tree-sitter/tree-sitter-haskell?tab=readme-ov-file#supported-language-extensions) 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:

```js

// 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](https://github.com/tree-sitter/tree-sitter-haskell) a piece of haskell code, returning its AST representation.

Example:

```js

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:

```js

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`.

```js

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.

```js

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

*/

```