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

## Information

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.

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

`.gen.ts` files are created by the [`@genType`](https://rescript-lang.org/docs/gentype/latest/getting-started) decorator, 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.

### Errors regarding the `rationale` package

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

As it says in the other `packages/*/README.md`s, building this package is an essential step of building other packages.
After pair programming with @Hazelfire, still need to fix playground scripts (rebase: README and index.js) 2022-03-23 22:34:50 +00:00			`# Squiggle language`

(rebase): README improvements, and other such things 2022-03-25 16:45:40 +00:00			`## Build for development`
Run prettier in squiggle-lang 2022-04-11 00:51:43 +00:00
			We assume that you ran `yarn` at the monorepo level.

			```sh
After pair programming with @Hazelfire, still need to fix playground scripts (rebase: README and index.js) 2022-03-23 22:34:50 +00:00			`yarn build`
			```

Run prettier in squiggle-lang 2022-04-11 00:51:43 +00:00			`yarn bundle` is needed for a deployment.

			`Other:`
fixed needed `yarn` commands in README.md 2022-03-25 00:21:34 +00:00
Run prettier in squiggle-lang 2022-04-11 00:51:43 +00:00			```sh
After pair programming with @Hazelfire, still need to fix playground scripts (rebase: README and index.js) 2022-03-23 22:34:50 +00:00			`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`
property test framework installed but not used; describe(means) section of unit tests filled out 2022-04-06 22:57:51 +00:00
Run prettier in squiggle-lang 2022-04-11 00:51:43 +00:00			`# where o := open in osx and o := xdg-open in linux,`
property test framework installed but not used; describe(means) section of unit tests filled out 2022-04-06 22:57:51 +00:00			`yarn coverage; o _coverage/index.html # produces coverage report and opens it in browser`
After pair programming with @Hazelfire, still need to fix playground scripts (rebase: README and index.js) 2022-03-23 22:34:50 +00:00			```

(rebase): README improvements, and other such things 2022-03-25 16:45:40 +00:00			`## Information`
Run prettier in squiggle-lang 2022-04-11 00:51:43 +00:00
(rebase): README improvements, and other such things 2022-03-25 16:45:40 +00:00			`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.`
After pair programming with @Hazelfire, still need to fix playground scripts (rebase: README and index.js) 2022-03-23 22:34:50 +00:00
(rebase): README improvements, and other such things 2022-03-25 16:45:40 +00:00			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.
Add documentation and packaging info to lang 2022-02-25 23:03:05 +00:00
(rebase): README improvements, and other such things 2022-03-25 16:45:40 +00:00			`If using this package for tests or as a dependency, typescript typings are available and recommended to be used.`
Add documentation and packaging info to lang 2022-02-25 23:03:05 +00:00
(rebase): README improvements, and other such things 2022-03-25 16:45:40 +00:00			`This package is mainly written in [ReScript](https://rescript-lang.org/), but has a typescript interface.`
Add documentation and packaging info to lang 2022-02-25 23:03:05 +00:00
(rebase): README improvements, and other such things 2022-03-25 16:45:40 +00:00			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`.
Add documentation and packaging info to lang 2022-02-25 23:03:05 +00:00
(rebase): README improvements, and other such things 2022-03-25 16:45:40 +00:00			`.gen.ts` files are created by the [`@genType`](https://rescript-lang.org/docs/gentype/latest/getting-started) decorator, 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.
Add documentation and packaging info to lang 2022-02-25 23:03:05 +00:00
(rebase): README improvements, and other such things 2022-03-25 16:45:40 +00:00			### Errors regarding the `rationale` package
Run prettier in squiggle-lang 2022-04-11 00:51:43 +00:00
(rebase): README improvements, and other such things 2022-03-25 16:45:40 +00:00			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.
Add documentation about rationale error 2022-02-25 23:06:25 +00:00
Add documentation and packaging info to lang 2022-02-25 23:03:05 +00:00			`## Distributing this package or using this package from other monorepo packages`
Run prettier in squiggle-lang 2022-04-11 00:51:43 +00:00
			As it says in the other `packages/*/README.md`s, building this package is an essential step of building other packages.