Merge pull request #142 from JordanMartinez/development

Make next minor release: PS-0.12.x-v0.9.6

.gitignore

@@ -19,5 +19,5 @@
 
 # For the benchmarking folder
 /**/tmp/
-# Since Benchotron is not yet in the default package set
-/**/*Benchmarking/psc-package.json
+# Since we need to use Spacchetti to install Benchotron
+/**/*Benchmarking/packages.json

00-Getting-Started/01-Install-Guide.md

@@ -15,18 +15,42 @@ If you ever want to support PureScript, consider making a pledge on its [Open Co
 
 ### Installation
 
-The [Purescript By Example book](https://leanpub.com/purescript/) demonstrates how to set up one's environment for PureScript `0.11.x` (outdated). Since the book's release, PureScript `0.12.0` has been released, which introduced breaking changes. Fortunately, Justin Woo explains how to set up one's environment for the `0.12.0` (since the article's publication, `0.12.1` has been released). If you just want to get things set up ASAP, follow the below summary of his article's instructions. If you want to understand why you should do these commands, read [his article here](https://qiita.com/kimagure/items/570e6f2bbce5b4724564):
+Justin Woo explains how to set up one's environment for the `0.12.x` release but has not been updated for two things. First, the PureScript release at the time was `0.12.0` but now `0.12.1` is out. Second, he did not include instructions for setting up [`spacchetti`](https://github.com/justinwoo/spacchetti) and its counterpart, `dhall`. Spacchetti is a project Justin later wrote to speed up tedious tasks that often arise when using `psc-package`.
+
+If you just want to get things set up ASAP, follow the below summary of his article's instructions + the Spacchetti stuff. If you want to understand why you should do these commands, read [his article here](https://qiita.com/kimagure/items/570e6f2bbce5b4724564):
 1. Install Node 8 or greater: https://nodejs.org/en/download/
 2. Set your npm prefix: `npm set prefix ~/.npm`
 3. Set your PATH: `export PATH="$HOME/.npm/bin:$PATH"`
-4. Install Purescript, pulp, and psc-package: `npm i -g purescript@0.12.1 pulp psc-package`
 
+NPM will then be used to install 4 packages
+- `purescript` - the PureScript binary
+- `pulp` - a build tool for PureScript
+- `psc-package` - a dependency manager for PureScript
+- `spacchetti` - already explained above
+
+To install them, run this command:
+```bash
+npm i -g purescript@0.12.1 pulp psc-package-bin-simple spacchetti-cli-bin-simple
+```
 The following commands should now work (the versions beside them are the versions I used when writing this project):
 ```bash
 purs --version        # 0.12.1
 pulp --version        # 12.3.0
 psc-package --version # 0.3.2
+spacchetti version    # 0.5.0.0
 ```
+
+In addition to the above packages, you also need to install `dhall-to-json`. [Dhall](https://github.com/dhall-lang/dhall-lang):
+> Dhall is a programmable configuration language that is not Turing-complete
+>
+> You can think of Dhall as: JSON + functions + types + imports
+
+Good news! You don't need to understand Dhall to use it (I've literally written the instructions / examples to copy/paste).
+
+To install `dhall-to-json` for your platform, see [this page](https://github.com/dhall-lang/dhall-lang/wiki/Getting-started%3A-Generate-JSON-or-YAML)
+
+See the `Build Tools/Tool Comparisons.md` file's "Why Spacchetti"'s section for more info about why `Spacchetti` even exists.
+
 ### Setting up your editor
 
 The following are instructions for setting up the Atom editor. For Emacs, Vim, or Visual Studio, [consult Justin Woo's post on the matter](https://qiita.com/kimagure/items/570e6f2bbce5b4724564#install-some-editor-plugins) and [the respective page in the documentation repo](https://github.com/purescript/documentation/blob/master/ecosystem/Editor-and-tool-support.md#emacs)

00-Getting-Started/03-Other-Important-Info.md

@@ -1,6 +1,11 @@
 # Other Important Info
 
-[Purescript By Example](https://leanpub.com/purescript/read#) is a now-outdated book that teaches Purescript. It covers Purescript `0.11.7` and not `0.12.0`, which introduced a lot of breaking changes. It's still a useful learning resource. However, be wary of any references to these [deprecated packages](https://github.com/purescript-deprecated) and read through the ReadMe in `ROOT_FOLDER/Hello-World/Console-Lessons/Effect-Eff-and-Aff` to understand how to translate the no-longer-used `Eff` type to `Effect` type.
+[Purescript By Example](https://leanpub.com/purescript/read#) is a book that teaches Purescript. Unfortunately, it is now outdated because it covers Purescript `0.11.7` and not `0.12.x`, which introduced a lot of breaking changes. However, it's still a useful learning resource.
+
+If you decide to read the book, here are things to be aware of:
+- be wary of any references to these [deprecated packages](https://github.com/purescript-deprecated)
+- Refer to `dwhitney` fork of the book's code, which is currently being updating to use `0.12.x` code [here](https://github.com/dwhitney/purescript-book/tree/0.12)
+- Refer to the ReadMe in `ROOT_FOLDER/Hello-World/Console-Lessons/Effect-Eff-and-Aff` to understand how to translate the no-longer-used `Eff` type to `Effect` type.
 
 ## Documenation
 

01-Build-Tools/01-Tool-Comparisons/01-Dependency-Managers.md

@@ -42,6 +42,58 @@ Now for a side-by-side comparison (an "apples to oranges" comparison)
 
 ^^ This is explained later in this folder ("Create Local Custom Package Set.md")
 
+### Why Spacchetti?
+
+#### Psc-Package Terms
+
+A **package** in this context is 4 things:
+    1. a Git repo
+    2. a tag in that repo
+    3. a set of its dependencies (which are also packages).
+    4. a name to refer to the combination of the above three things
+
+Thus, a package is a unique named `repo-tag-dependencies` combination (e.g. `prelude` could indicate the [Prelude repo at the 'v0.4.1' tag](https://github.com/purescript/purescript-prelude/tree/v4.1.0)).
+
+A **package set** consists of a set of packages. It's a JSON file that maps a package name to its corresponding repo-tag-dependencies combination.
+
+#### The Cause of the Pain Point
+
+When using Bower, you have no idea whether a package (code that was released at some tag) will compile with some other package. AFAIK, Phil Freeman (creator of PureScript) and others created `psc-package` to fix this problem. Currently, Justin Woo maintains it.
+
+Justin has defined an "official" / "standard" package set [here](https://github.com/purescript/package-sets/blob/master/packages.json) that `psc-package` uses to download and compile one's dependencies. Why? So that he can prove via CI that all the packages in the set work/compile together without issue. This addresses the pain point from Bower. Moreover, it also stops each developer who uses `psc-package` from wasting time verifying the same package set locally as it can be done only once in Justin's repo.
+
+This "guaranteed to work together" feature comes with implications:
+- The "official" / "standard" package set must be immutable. Our confidence that packages work together is broken as soon as a new package is added. Adding a package requires reverifying that all the packages work when the package is added.
+- Following from this, changing the package set in any way requires Justin to re-verify it via CI and make a new release of the "official" / "standard" package set.
+
+These implications create the following problems:
+1. Your workflow is blocked when you need a dependency/library that is not already defined as a package within the "official" / "standard" package set.
+  - When this occurs, you or the library/dependency author have to add it to the "official" / "standard" package set yourself, AND THEN wait for Justin to merge that pull request, AND THEN wait for verification to finish (it might fail verification in some cases), AND THEN wait for Justin to make a new relase of the "official" / "standard" package set. That's a lot of waiting.
+2. Your workflow is blocked when you need a dependency/library that is in the package set, but which needs to be patched/changed in some way. For example, a library for handling a `MouseEvent`does not include `mouseEvent.offsetX` ([true story](https://pursuit.purescript.org/packages/purescript-web-uievents/1.0.0/docs/Web.UIEvent.MouseEvent#v:clientX))
+  - This situation is the same as the above except now you or the author need to submit a PR to the library/dependency to fix the issue, AND THEN wait for the library maintainer to make a new release, AND THEN go through all of the steps above.
+
+Moreover, you likely only need to make some change in only one project. It's not worth it to submit a PR, either to Justin's package set repo or a library's repo, because it's custom to your use cases.
+
+Fortunately, `psc-package` does not know about or even have a notion of the "official" / "standard" package set. A developer can still verify packages in a package set on their own. However, manipulating the packaget set's files is very tedious.
+
+To add a new or patch an existing package, here's the steps one has to take (where items marked with `*` are the tedious parts):
+- `*`Create a local copy of the "official" / "standard" package set
+- `*`Add a new package to or modify an existing package's repo/tag in the local package set
+- `*`Locally verify that the package set compiles together
+- `*`Refer to the local package set in one's `psc-package.json` file instead of the "official" / "standard" package set.
+- Re-install the packages and continue coding from there.
+
+#### Solving the Pain Point
+
+Justin fixed this by using `Spacchetti` and `Dhall`. Now, one can easily and quickly patch/change/add a package in some set using Dhall by following these steps:
+1. Run `spacchetti local-setup`
+2. Patch/Change/Add packages to the package set by modifying the `packages.dhall` file, which now includes my instructions and examples for how to do so (this was added [here](https://github.com/justinwoo/spacchetti-cli/pull/18/commits/f949f1ca951be3570a38c0f007b5a28ecf920cf1#diff-eb94b4b0f53b1dc125cfee4342687dd0R2))
+3. Run `spacchetti insdhall`
+4. Run `psc-package verify` (if you know it works, you can skip this step)
+5. Run `psc-package install`
+
+In other words, a potentially weeks-long problem can become a few-seconds fix.
+
 ## The `Batteries` Prelude
 
 The closest idea Bower has to a `package set` is the [`batteries` prelude](https://github.com/tfausak/purescript-batteries) that is no longer maintained and doesn't work for PureScript 0.12.0. I looked through it a month ago and updated the dependencies in their `bower.json` file to [this file](updated-batteries.json), which enables one to use the [Halogen](https://github.com/slamdata/purescript-halogen) library, v4.0.0. (Note: this file is not a correctly-formatted Bower.json file). I abandoned it after I learned about psc-package, but I'm including it here in case others want to use Bower and find a use for it.

01-Build-Tools/03-New-Project-From-Start-to-Finish.md

@@ -21,7 +21,7 @@ pulp --psc-package init projectName
 # default package set. This is the recommended approach.
 # (See the latest release here):
 #    https://github.com/purescript/package-sets/releases
-psc-package init --set psc-0.12.0-20180819 --source https://github.com/purescript/package-sets.git
+psc-package init --set psc-0.12.1 --source https://github.com/purescript/package-sets.git
 
 # 2b) Open the below file and change the 'name' field to your project's name.
 #

01-Build-Tools/04-Create-Local-Custom-Package-Set.md

@@ -1,6 +1,6 @@
 # Create Local Custom Package Set
 
-I'm writing this because I finally came across a situation where I needed a package via `psc-package` and it was not already included in the default package-set.
+**These are the steps one must take to change something in the "official" / "standard" package-set. This file is for legacy purpose; you should be using `spacchetti` now.**
 
 Thus, here's the steps I took to make it work:
 ```bash

11-Syntax/03-Type-Level-Programming-Syntax/ReadMe.md

@@ -3,3 +3,7 @@
 Read the files in order. It may take a few read-throughs for it to make sense as to why some things are needed but it will make sense eventually.
 
 Note: there is an annoyance that can occur if you play around with the code: due to using the same names for some things, the IDE may try to import these names from other modules. If it does so, it may result it some definition being declared twice in the same file and produce a compiler error. If you experience such a problem, check the top of the file and delete any imports there.
+
+## Other Learning Sources
+
+Consider purchasing [Thinking with Types](https://leanpub.com/thinking-with-types/), a book that claims to be "the comprehensive manual for type-level programming".

21-Hello-World/04-Debugging/src/02-Custom-Type-Errors/01-Overview-API.purs

@@ -36,6 +36,9 @@ import Prim.TypeError (
 data Doc_
   = Text_ String      -- wraps a Symbol
   | Quote_ String     -- the Type's name as a Symbol
+  | QuoteLabel_ String -- Similar to Text but handles things differently
+                       -- Used particularly for 'labels', the 'keys'
+                       -- in rows/records (see functions file)
   | Beside_ Doc_ Doc_ -- same as "left <> right" ("leftright")
   | Above_ Doc_ Doc_  -- same as "top" <> "\n" <> "bottom" ("top\nbottom")
 

21-Hello-World/04-Debugging/src/02-Custom-Type-Errors/03-Functions.purs

@@ -1,5 +1,7 @@
 module ConsoleLessons.CustomTypeErrors.Functions where
 
+import Prelude
+import Data.Symbol (SProxy(..))
 import Effect (Effect)
 import Effect.Console (log)
 
@@ -10,11 +12,14 @@ import Data.Unit (Unit)
 import Data.Function (($))
 import Control.Bind (discard)
 
-import Prim.TypeError (kind Doc, Text, Quote, Above, Beside, class Warn, class Fail)
+import Prim.TypeError (kind Doc, Text, Quote, Above, Beside, QuoteLabel, class Warn, class Fail)
 
 data Doc_
   = Text_ String      -- wraps a Symbol
   | Quote_ String     -- the Type's name as a Symbol
+  | QuoteLabel_ String -- Similar to Text but handles things differently
+                       -- Used particularly for 'labels', the 'keys'
+                       -- in rows/records (see below)
   | Beside_ Doc_ Doc_ -- same as "left <> right" ("leftright")
   | Above_ Doc_ Doc_  -- same as "top" <> "\n" <> "bottom" ("top\nbottom")
 
@@ -47,10 +52,31 @@ failValue = 20
 regularValue :: Int
 regularValue = 4
 
+-- QuoteLabel vs Text
+labelAsText :: forall l. Warn
+  ( Text "Text Label " <> Text l
+  ) => SProxy l -> String
+labelAsText _ = ""
+
+labelAsQuote :: forall l. Warn
+  ( Text "Quote Label " <> QuoteLabel l
+  ) => SProxy l -> String
+labelAsQuote _ = ""
+
 main :: Effect Unit
 main = do
   log $ show regularValue
   log $ show warnValue
 
+  -- Demonstrates the difference between Text and QuoteLabel
+  log $ show (labelAsText (SProxy :: SProxy "boo"))
+  log $ show (labelAsQuote (SProxy :: SProxy "boo"))
+
+  log $ show (labelAsText (SProxy :: SProxy "b\"oo"))
+  log $ show (labelAsQuote (SProxy :: SProxy "b\"oo"))
+
+  log $ show (labelAsText (SProxy :: SProxy "b o o"))
+  log $ show (labelAsQuote (SProxy :: SProxy "b o o"))
+
   -- Uncomment the next line, save the file, run it, and see what happens
   -- log $ show failValue

21-Hello-World/05-Testing/psc-package.json

@@ -3,12 +3,8 @@
   "set": "psc-0.12.1",
   "source": "https://github.com/purescript/package-sets.git",
   "depends": [
-    "exceptions",
-    "console",
-    "strings",
-    "quickcheck-laws",
+    "newtype",
     "quickcheck",
-    "spec",
     "psci-support",
     "effect",
     "prelude"

21-Hello-World/06-Benchmarking/ReadMe.md

@@ -8,7 +8,7 @@ Purescript has a few benchmarking libraries:
 | [purescript-minibench](https://pursuit.purescript.org/packages/purescript-minibench/2.0.0/docs/Performance.Minibench) | Up-to-date | Provides quick estimates but not very accurate benchmarks
 | [purescript-benchmark](https://pursuit.purescript.org/packages/purescript-benchmark/0.1.0) | Outdated (PS `0.11.7`) | Doesn't require QuickCheck<br>Outputs results in Node and Browser<br>Output is full ASCII table with percentage values
 
-In this folder, we'll be covering `benchotron` because it works for `0.12.0` and has finer accuracy than `minibench` and includes graphs.
+In this folder, we'll be covering `benchotron` because it works for `0.12.x` and has finer accuracy than `minibench` and includes graphs.
 
 This benchotron graph...
 
@@ -20,39 +20,22 @@ This benchotron graph...
 
 `Benchotron` is a Purescript library that provides bindings to [`Benchmark.js`](https://benchmarkjs.com/). As such, you will need to install that library via the command below:
 ```bash
-# Note: If you install this locally and then run the benchmark
-# it will succeed. If you install it globally, Node won't
-# be able to find `benchmark`.
+# Note: This must be installed locally for the code to work.
+# If you install it globally, Node won't be able to find `benchmark`.
 npm install benchmark
 ```
 
-Since `benchotron` is not in the default package set (yet), you'll need to create your own local custom package set. Fortunately, I've done most of the tedious work for you. Follow these instructions:
+Since `benchotron` is not in the default package set (yet), you'll need to use `spacchetti` to create your own local custom package set by following these instructions:
 ```bash
-# 1. Make the necessary directory
-mkdir -p .psc-package/custom-set--psc-0.12.0-20180828
-# 2. Copy the packages.json file into the folder
-cp packages.json .psc-package/custom-set--psc-0.12.0-20180828/packages.json
+# I've already ran `spacchetti local-setup`
+# and configured the 'packages.dhall' file.
+# See this folder as an example of what you would need to do
+# if you had to do it on your own.
+
+# So, we just need to install the local custom package set
+spacchetti insdhall
+psc-package install
 ```
-3. Create a file called `psc-package.json` in the folder, `Hello World/Benchmarking`.
-4. Copy the following JSON into `psc-package.json` file:
-```json
-{
-  "name": "includes-benchotron",
-  "set": "custom-set--psc-0.12.0-20180828",
-  "source": "file:///home/user/path-to-containing-folder/purescript-reference/21-Hello-World/06-Benchmarking/packages.json",
-  "depends": [
-    "console",
-    "quickcheck",
-    "psci-support",
-    "effect",
-    "prelude",
-    "benchotron"
-  ]
-}
-```
-5. Update the `/home/user/path-to-containing-folder/` part of the file path in the `source` field to the purescript-reference folder on your local computer
-6. Save the `psc-package.json` file
-7. Install the packages (no need to verify them): `psc-package install`
 
 You can now use `benchotron` via psc-package.
 
@@ -70,6 +53,5 @@ pulp --psc-package run --src-path "benchmark" -m Benchmarking.Syntax.Benchotron
 
 In real-world projects, one would run this command:
 ```bash
-pulp --psc-package run -m Performance.ModulePath.To.MainModule --src-
-path benchmark --include "src:test"
+pulp --psc-package run -m Performance.ModulePath.To.MainModule --src-path "benchmark" --include "src:test"
 ```