squiggle/packages/squiggle-lang/README.md

# Squiggle language

# Build for development
We assume that you ran `yarn` at the monorepo level. 
``` sh
yarn build
```

`yarn bundle` is needed for a deployment. 

Other: 
``` sh
yarn start  # listens to files and recompiles at every mutation
yarn test
yarn test:watch  # keeps an active session and runs all tests at every mutation

# where o := open in osx and o := xdg-open in linux,  
yarn coverage; o _coverage/index.html  # produces coverage report and opens it in browser
```

# TODO: clean up this README.md 

# Squiggle Language
Squiggle is a language for representing probability distributions, as well as 
functions that return probability distributions. Its original intended use is
for improving epistemics around EA decisions.

This package, @quri/squiggle-lang, contains the core language of squiggle. The main
feature revolves around evaluating squiggle expressions. Currently the package
only exports a single function, named "run", which from a squiggle string returns
an object representing the result of the evaluation.

If using this package for tests or as a dependency, typescript typings are available
and recommended to be used.

## Building this package
This package doesn't have any dependencies on any other packages within the monorepo,
so if you wish you can generally ignore lerna or yarn workspaces when dealing
with this package in particular.

First, as per any node package, you will need to install dependencies, we recommend
using [yarn](https://classic.yarnpkg.com/en/).

```bash
yarn
```

This package is mainly written in [ReScript](https://rescript-lang.org/). But has
a typescript interface.

ReScript has an interesting philosophy of not providing much in the way of effective
build tools. Every ReScript file is compiled into .bs.js and .gen.ts files with the same name
and same location, and then you can use these files in other js files to
create your program. To generate these files to build the package, you run
`yarn build`.

```bash
yarn build
```

.gen.ts files are created by [genType](https://rescript-lang.org/docs/gentype/latest/getting-started),
which creates typescript typings for needed parts of the codebase so that they
can be easily used in typescript. These .gen.ts files reference the .bs.js files
generated by rescript.

You can also go `yarn start` for the purposes of watching for file changes and 
rebuilding every time there is one.

Finally, `yarn test` runs the current test suite over the language.

You may notice sometimes, that there are errors about the `rationale` package.
If you ever get these errors, `yarn build` should fix this issue. These errors
occur because `yarn build` also needs to create build files that are in `node_modules`.
So if you replace `node_modules` you may need to rebuild to get those files back.

## Distributing this package or using this package from other monorepo packages
If you would like to distribute this package, run `yarn package` to compile all the js
and typescript into the `dist` directory. This `dist` directory code is what's
referenced by other packages in the monorepo.

## Using this package
The return type of this packages only experted function `run` is currently quite 
complicated, as it has to return either a number, or a distribution, or even
a representation of a function of distributions. Currently the export is simply
the generated type that rescript creates, and can be quite confusing. We therefore
highly recommend the use of typescript when creating tests or using this package.

## Potential Issues
If you experiment with generating different types of .gen.ts files and similar, note that they won't be caught by git (because they are in .gitignore). Make sure you delete these extra files, once they are unecessary.
```
    rm src/rescript/**/*.gen.ts
```