Update repo for PureScript v0.15.0 release (documentationjs#438)

* First draft of documentation update for v0.15 (documentationjs#421)

* First draft of documentation update for v0.15

* Describe ambiguous matches in instance chains (documentationjs#392)

* Update tool versions

* Update parsing library changelog

* Update 0.15 guides to account for `Stream.write` breaking change

Co-authored-by: sigma-andex <[email protected]>
Co-authored-by: Ryan Hendrickson <[email protected]>

Author: 3 people

guides/FFI-Tips.md

@@ -11,7 +11,7 @@ foreign import joinPath :: FilePath -> FilePath -> FilePath
 ```
 
 ```javascript
-exports.joinPath = function(start) {
+export function joinPath(start) {
   return function(end) {
     return require('path').join(start, end);
   };
@@ -27,7 +27,7 @@ foreign import joinPathImpl :: Fn2 FilePath FilePath FilePath
 ```
 
 ```javascript
-exports.joinPathImpl = require('path').join;
+export { join as joinPathImpl } from 'path';
 ```
 
 However, these `Fn0`..`Fn10` types cannot be applied as normal PureScript functions, they require a corresponding `runFn0`..`runFn10` call to execute. The `runFn` definitions essentially do the work of taking a multi-argument function and returning a curried version for you.
@@ -62,7 +62,7 @@ doSomething fn x = runFn2 doSomethingImpl fn x
 ```
 
 ```javascript
-exports.doSomethingImpl = function(fn, x) {
+export function doSomethingImpl(fn, x) {
   if (fn(x)) {
     return Data_Maybe.Just.create(x);
   } else {
@@ -104,7 +104,7 @@ showSomething x = runFn3 showSomethingImpl isJust show x
 ```
 
 ```javascript
-exports.doSomethingImpl = function(isJust, show, value) {
+export function doSomethingImpl(isJust, show, value) {
   if (isJust(value)) {
     return "It's something: " + show(value);
   } else {
@@ -122,7 +122,7 @@ By moving the `show` reference out to `showSomething` the compiler will pick the
 In order to avoid prematurely evaluating effects (or evaluating effects that should not be evaluated at all), PureScript wraps them in constant functions:
 
 ```javascript
-exports.myEffect = function() {
+export function myEffect() {
   return doSomethingEffectful(1, 2, 3);
 }
 ```

guides/FFI.md

@@ -33,18 +33,11 @@ This function finds the greatest common divisor of two numbers by repeated subtr
 To understand how this function can be called from Javascript, it is important to realize that PureScript functions always get turned into Javascript functions _of a single argument_, so we need to apply its arguments one-by-one:
 
 ``` javascript
-var Test = require('Test');
-Test.gcd(15)(20);
+import { gcd } from 'Test';
+gcd(15)(20);
 ```
 
-Here, I am assuming that the code was compiled with `psc`, which compiles PureScript modules to CommonJS modules. For that reason, I was able to reference the `gcd` function on the `Test` object, after importing the `Test` module using `require`.
-
-You might also like to bundle JavaScript code for the browser, using `purs bundle`. In that case, you would access the `Test` module on the global namespace, which defaults to `PS`:
-
-``` javascript
-var Test = PS.Test;
-Test.gcd(15)(20);
-```
+Here, I am assuming that the code was compiled with `psc`, which compiles PureScript modules to ES modules. For that reason, I was able to import the `gcd` function from the `Test` module.
 
 #### Understanding Name Generation
 
@@ -85,14 +78,12 @@ The general rule regarding types is that you can enforce as little or as much ty
 In PureScript, JavaScript code is wrapped using a _foreign module_. A foreign module is just a CommonJS module which is associated with a PureScript module. Foreign modules are required to adhere to certain conventions:
 
 - The name of the foreign module must be the same as its companion PureScript module, with its extension changed to `.js`. This associates the foreign module with the PureScript module.
-- All exports must be of the form `exports.name = value;`, specified at the top level.
+- All exports must be of the form `export const name = value;` respectively `export function name() { ... }` for functions, specified at the top level.
 
 Here is an example, where we export a function which computes interest amounts from a foreign module:
 
 ```javascript
-"use strict";
-
-exports.calculateInterest = function(amount) {
+export function calculateInterest(amount) {
   return amount * 0.1;
 };
 ```
@@ -114,9 +105,7 @@ PureScript functions are curried by default, so Javascript functions of multiple
 Suppose we wanted to modify our `calculateInterest` function to take a second argument:
 
 ```javascript
-"use strict";
-
-exports.calculateInterest = function(amount, months) {
+export function calculateInterest(amount, months) {
   return amount * Math.exp(0.1, months);
 };
 ```
@@ -141,9 +130,7 @@ calculateInterestCurried = runFn2 calculateInterest
 An alternative is to use curried functions in the native module, using multiple nested functions, each with a single argument, as the runtime representation of the function type constructor `(->)` dictates:
 
 ```javascript
-"use strict";
-
-exports.calculateInterest = function(amount) {
+export function calculateInterest(amount) {
   return function(months) {
     return amount * Math.exp(0.1, months);
   };

guides/Getting-Started.md

@@ -256,9 +256,10 @@ The `spago run` command can be used to compile and run the `Main` module:
 Spago can be used to turn our PureScript code into JavaScript suitable for use in the web browser by using the `spago bundle-app` command:
 
     $ spago bundle-app
-    ...
-    Build succeeded.
-    Bundle succeeded and output file to index.js
+      index.js  11.8kb
+
+    ⚡ Done in 14ms
+    [info] Bundle succeeded and output file to index.js
 
 All the code in the `src` directory and any project dependencies have been compiled to JavaScript. The resulting code is bundled as `index.js` and has also had any unused code removed, a process known as dead code elimination. This `index.js` file can now be included in an HTML document. 
 
@@ -284,41 +285,35 @@ Open this `index.html` file in your web browser. The page will be blank, but if
 If you open `index.js`, you should see a few compiled modules which look like this:
 
 ```javascript
-// Generated by purs bundle 0.13.6
-var PS = {};
-
-// ...
-
-(function($PS) {
-  "use strict";
-  $PS["Euler"] = $PS["Euler"] || {};
-  var exports = $PS["Euler"];
-  var Data_EuclideanRing = $PS["Data.EuclideanRing"];
-  var Data_Foldable = $PS["Data.Foldable"];
-  var Data_List = $PS["Data.List"];
-  var Data_List_Types = $PS["Data.List.Types"];
-  var Data_Semiring = $PS["Data.Semiring"];
-  var ns = Data_List.range(0)(999);
-  var multiples = Data_List.filter(function (n) {
-      return Data_EuclideanRing.mod(Data_EuclideanRing.euclideanRingInt)(n)(3) === 0 || Data_EuclideanRing.mod(Data_EuclideanRing.euclideanRingInt)(n)(5) === 0;
-  })(ns);
-  var answer = Data_Foldable.sum(Data_List_Types.foldableList)(Data_Semiring.semiringInt)(multiples);
-  exports["answer"] = answer;
-})(PS);
-
-(function($PS) {
-  // Generated by purs version 0.13.6
-  "use strict";
-  $PS["Main"] = $PS["Main"] || {};
-  var exports = $PS["Main"];
-  var Data_Show = $PS["Data.Show"];
-  var Effect_Console = $PS["Effect.Console"];
-  var Euler = $PS["Euler"];
-  var main = Effect_Console.log("The answer is " + Data_Show.show(Data_Show.showInt)(Euler.answer));
-  exports["main"] = main;
-})(PS);
-
-PS["Main"].main();
+(() => {
+  // output/Data.Show/foreign.js
+  var showIntImpl = function(n) {
+    return n.toString();
+  };
+
+  ...
+
+  // output/Euler/index.js
+  var ns = /* @__PURE__ */ function() {
+    return range2(0)(999);
+  }();
+  var multiples = /* @__PURE__ */ function() {
+    return filter(function(n) {
+      return mod(euclideanRingInt)(n)(3) === 0 || mod(euclideanRingInt)(n)(5) === 0;
+    })(ns);
+  }();
+  var answer = /* @__PURE__ */ function() {
+    return sum(foldableList)(semiringInt)(multiples);
+  }();
+
+  // output/Main/index.js
+  var main = /* @__PURE__ */ function() {
+    return log("The answer is " + show(showInt)(answer));
+  }();
+
+  // <stdin>
+  main();
+})();
 ```
 
 This illustrates a few points about the way the PureScript compiler generates JavaScript code:
@@ -331,17 +326,17 @@ This illustrates a few points about the way the PureScript compiler generates Ja
 
 These points are important since they mean that PureScript generates simple, understandable code. The code generation process, in general, is quite a shallow transformation. It takes relatively little understanding of the language to predict what JavaScript code will be generated for a particular input.
 
-### Compiling CommonJS Modules
+### Compiling ES Modules
 
-Spago can also be used to generate CommonJS modules from PureScript code. This can be useful when using NodeJS, or just when developing a larger project which uses CommonJS modules to break code into smaller components.
+Spago can also be used to generate ES modules from PureScript code. This can be useful when using NodeJS, or just when developing a larger project which uses ES modules to break code into smaller components.
 
-To build CommonJS modules, use the `spago build` command:
+To build ES modules, use the `spago build` command:
 
     $ spago build
     ...
     Build succeeded.
 
-The generated modules will be placed in the `output` directory by default. Each PureScript module will be compiled to its own CommonJS module, in its own subdirectory.
+The generated modules will be placed in the `output` directory by default. Each PureScript module will be compiled to its own ES module, in its own subdirectory.
 
 ### What Next?
 

guides/PSCi.md

@@ -14,7 +14,7 @@ $ spago init                 # Initialize a Spago environment
 $ spago repl                 # Fire up the interpreter psci
 
 ...
-PSCi, version 0.13.6
+PSCi, version 0.15.0
 Type :? for help
 
 import Prelude

guides/PureScript-Without-Node.md

@@ -59,24 +59,27 @@ Compiling Effect.Console
 
 #### Bundling JavaScript for the Browser
 
-To bundle the generated Javascript code, we will use `purs bundle`.
+To bundle the generated Javascript code into a single file, we will use `spago bundle`.
 
-`purs bundle` takes a collection of CommonJS module files as input, and generates a single JavaScript file.
+`spago bundle-app` take the module with the main as input, and generates a single self-contained JavaScript file.
 
-Run `purs bundle` with the following arguments:
+Run `spago bundle-app` with the following arguments:
 
-```text
-$ purs bundle output/*/{index,foreign}.js --module Main --main Main
+```bash
+$ spago bundle-app --main Main --to index.js
 ```
 
-The `--module` argument specifies an _entry-point_ module, which will be used to determine dead code which can be removed. For our purposes, we only care about bundling the CommonJS module corresponding to the Main PureScript module and its transitive dependencies.
-
 The `--main` argument will make the output JavaScript file an executable by adding a line of JavaScript to it which runs the `main` function in the specified module.
 
-If everything worked, you should see about 100 lines of JavaScript printed out. This can optionally be redirected to a file with the `--output`/`-o` argument.
+If you want to bundle for Node.js, you can use the following command:
+
+```bash
+spago bundle-app --main Main --to index.js --platform node
+```
+You should be able to execute the generated JavaScript using Node.js.
 
-You should be able to execute the generated JavaScript using NodeJS. If your PureScript code uses FFI files which `require` NPM modules, you'll need to use a JavaScript bundler, like Webpack or Browserify, before running it in the browser.
+For more information, see the [spago documentation](https://www.github.com/purescript/spago).
 
 #### Conclusion
 
-I've shown how it's possible to get started with PureScript without using the tools from the NodeJS ecosystem. Obviously, for larger projects, it takes some work to manage library dependencies this way, which is why the PureScript community has decided to reuse existing tools. However, if you need to avoid those tools for any reason, it is possible to script some standard tasks without them.
+I've shown how it's possible to get started with PureScript without using the tools from the Node.JS ecosystem. Obviously, for larger projects, it takes some work to manage library dependencies this way, which is why the PureScript community has decided to reuse existing tools. However, if you need to avoid those tools for any reason, it is possible to script some standard tasks without them.

language/Type-Classes.md

@@ -53,6 +53,26 @@ main = do
   log $ myShow MysteryItem -- Invalid
 ```
 
+When type variables are present in the constraint being solved, the question of whether an instance in a chain matches is a little subtle. A type variable in the constraint is treated existentially—it represents some concrete type, but the constraint solver isn't allowed to assume that it is any particular type. This means that, when evaluating an instance as a solution for a particular constraint, there are three possible outcomes for the instance: it can match, it can fail to match, or it can be ambiguous. An ambiguous instance is one that could match the constraint only if one or more of the variables in the constraint happened to represent a particular type.
+
+```purescript
+class MyShow a where
+  myShow :: a -> String
+
+instance showStringTuple :: MyShow a => MyShow (Tuple String a) where
+  myShow (Tuple s a) = s <> ": " <> myShow a
+
+else instance showA :: MyShow a where
+  myShow _ = "Invalid"
+
+f :: forall l r. Tuple l r -> String
+f = myShow -- error: no instance found
+```
+
+In this example, `f` needs an instance of `MyShow (Tuple l r)`. The `showStringTuple` is an ambiguous match for this constraint, because it would only match if `l` represented the type `String`. But `f` needs an implementation that will work for all `l`, so this can't be used as a full match.
+
+Ambiguous instances are mostly treated the same as an instance that fails to match, with this exception. If an instance in an instance chain fails to match, the compiler will try the next instance in the chain. But if an instance in an instance chain is an ambiguous match, the compiler will not consider any more instances in that chain. In the above example, the compiler will report that no instance was found for `MyShow (Tuple l r)` in `f`, even though the `showA` instance could have been a match, because the ambiguous `showStringTuple` prevents `showA` from being considered.
+
 ## Multi-Parameter Type Classes
 
 TODO. For now, see the section in [PureScript by Example](https://book.purescript.org/chapter6.html#multi-parameter-type-classes).

migration-guides/0.15-Ecosystem-Update.md

@@ -308,7 +308,19 @@ Breaking changes:
 
   To get the `ParserT` internal state, call `getParserT` instead of `get`.
 
-- Add the `anyTill` primitive `String` combinator. ([#186](https://github.com/purescript-contrib/purescript-parsing/pull/186) by @jamesdbrock)
+New features:
+- Add the `anyTill` primitive `String` combinator. (#186 by @jamesdbrock)
+- Add the `Parsing.String.Replace` module, copied from
+  https://github.com/jamesdbrock/purescript-parsing-replace (#188 by @jamesdbrock)
+  `streamEditT` can be written in terms of `replaceT`.
+
+  `streamEditT input sep editor = replaceT input (sep >>= editor >>> lift)`
+
+  (#188 by @jamesdbrock, #194 by @jamesdbrock)
+- Add the `advance` and `manyIndex` combinators. (#193 by @jamesdbrock)
+
+Bugfixes:
+- Improve correctness and speed of `number` and `intDecimal`. (#189 by @jamesdbrock)
 
 ### `profunctor-lenses`
 
@@ -432,5 +444,8 @@ Breaking changes:
 
 ### `node-streams`
 
+Breaking changes:
+- Update `write` callback to include `Error` arg ([#40](https://github.com/purescript-node/purescript-node-streams/pull/40) by @JordanMartinez)
+
 Other improvements:
 - Fix `Gzip` example ([#17](https://github.com/purescript-node/purescript-node-streams/pull/17), [#36](https://github.com/purescript-node/purescript-node-streams/pull/36) by @matthewleon and @JordanMartinez)

migration-guides/0.15-Migration-Guide.md

@@ -7,9 +7,11 @@ Compiler releases are often accompanied by breaking changes in the core librarie
 ## Tooling
 
 - `purescript-psa` does not need to be updated.
-- `spago` needs to be updated to `vT.B.D`.
+- `spago` needs to be updated to `v0.20.8`.
 - `pulp` needs to be updated to `v16.0.0`.
-- `purs-tidy` needs to be updated to `vT.B.D`.
+- `purs-tidy`:
+    - `0.7.2`, the latest version as of this writing, will only format your `0.15.0` code if you are not using type-level integers syntax.
+    - A future release should address this issue.
 
 ## ES modules migration guide
 
@@ -736,6 +738,20 @@ Key differences are:
 
 ## Breaking Changes in the `purescript-node` libraries
 
+### Expose the `Error` arg to `Stream.write`/`Stream.writeString (`purescript-node-streams`)
+
+The `Stream.write` and `Stream.writeString` have a callback function. The type signature for this binding was inaccurate because an `Error` arg is passed to that function but the type signature is `Effect Unit` rather than `Error -> Effect Unit`.
+
+This type signature was updated to be more accurate
+```diff
+-write :: forall r. Writable r -> Buffer ->           Effect Unit  -> Effect Boolean
++write :: forall r. Writable r -> Buffer -> (Error -> Effect Unit) -> Effect Boolean
+```
+
+**To fix**:
+- if you want to keep your current behavior, wrap your `Effect Unit` code in `const` (e.g. `pure unit` -> `const $ pure unit`)
+- if you want to use the `Error` arg, you can use `\err -> ...`
+
 ### Expose the `recursive` field in `mkdir'`'s options arg (`purescript-node-fs`/`purescript-node-fs-aff`)
 
 Previously, `mkdir` did not expose all the fields in the options arg. So, trying to run something like `mkdir "foo/bar/baz" { recursive: true }` wasn't possible without writing your own FFI to `mkdir`. The `recursive` option has now been exposed.