From 84364fe95db16ccf2fd3267602faf2645aa9ae07 Mon Sep 17 00:00:00 2001 From: Sam Nolan Date: Sat, 26 Feb 2022 10:03:05 +1100 Subject: [PATCH 1/2] Add documentation and packaging info to lang --- package.json | 3 +- packages/squiggle-lang/README.md | 54 ++++++++++++++++++++++++++++ packages/squiggle-lang/package.json | 7 ++-- packages/squiggle-lang/tsconfig.json | 16 +++++++++ 4 files changed, 77 insertions(+), 3 deletions(-) create mode 100644 packages/squiggle-lang/README.md create mode 100644 packages/squiggle-lang/tsconfig.json diff --git a/package.json b/package.json index fff2def6..5c28af6b 100644 --- a/package.json +++ b/package.json @@ -3,5 +3,6 @@ "devDependencies": { "lerna": "^4.0.0" }, - "name": "squiggle" + "name": "squiggle", + "workspaces": ["packages/*"] } diff --git a/packages/squiggle-lang/README.md b/packages/squiggle-lang/README.md new file mode 100644 index 00000000..4563355d --- /dev/null +++ b/packages/squiggle-lang/README.md @@ -0,0 +1,54 @@ +# 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, @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 a .bs.js file with the same name +and same location, and then you can use these .bs.js files in other js files to +create your program. To generate this .bs.js files to build the package, you run +`yarn build`. + +```bash +yarn build +``` + +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. + +## 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. diff --git a/packages/squiggle-lang/package.json b/packages/squiggle-lang/package.json index 0a652f9f..86aade3e 100644 --- a/packages/squiggle-lang/package.json +++ b/packages/squiggle-lang/package.json @@ -11,7 +11,8 @@ "test": "jest", "test:ci": "yarn jest ./__tests__/Lodash__test.re", "watch:test": "jest --watchAll", - "watch:s": "yarn jest -- Converter_test --watch" + "watch:s": "yarn jest -- Converter_test --watch", + "package": "tsc" }, "keywords": [ "Rescript" @@ -40,5 +41,7 @@ "rescript": "^9.1.4", "ts-jest": "^27.1.3", "typescript": "^4.5.5" - } + }, + "main": "./dist/js/index.js", + "types": "./dist/js/index.d.ts" } diff --git a/packages/squiggle-lang/tsconfig.json b/packages/squiggle-lang/tsconfig.json new file mode 100644 index 00000000..d5b49ca4 --- /dev/null +++ b/packages/squiggle-lang/tsconfig.json @@ -0,0 +1,16 @@ +{ + "compilerOptions": { + "module": "commonjs", + "allowJs": true, + "noImplicitAny": true, + "removeComments": true, + "preserveConstEnums": true, + "sourceMap": true, + "outDir": "./dist", + "declarationDir": "./dist", + "declaration": true + }, + "target": "ES6", + "include": ["src/**/*"], + "exclude": ["node_modules", "**/*.spec.ts"] +} From 24d565b7ef1c8d3cf169f0f75d5f46df6a7c4d74 Mon Sep 17 00:00:00 2001 From: Sam Nolan Date: Sat, 26 Feb 2022 10:06:25 +1100 Subject: [PATCH 2/2] Add documentation about rationale error --- packages/squiggle-lang/README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/squiggle-lang/README.md b/packages/squiggle-lang/README.md index 4563355d..35c4a4ae 100644 --- a/packages/squiggle-lang/README.md +++ b/packages/squiggle-lang/README.md @@ -41,6 +41,11 @@ 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