From ff5c484e3de486f0baf00fb75c0a8d9c7a5388f4 Mon Sep 17 00:00:00 2001 From: JordanMartinez Date: Mon, 9 Aug 2021 21:16:09 -0700 Subject: [PATCH] Make next major release: v0.14.x-0.30.0 (#571) * Ensure .ci dir is not included in mdbook output * Update purs to v0.14.3 * Upgrade to latest package set * Link to `aftok` * Link to 'final tagless have little to do with typeclasses' * Add note about purs-tidy and pose PS formatters --- .procedures/redeploy-book.sh | 2 +- 01-Getting-Started/04-Install-Guide.md | 9 +++++-- 03-Build-Tools/05-Formatters.md | 25 +++++++++++++++++++ .../05-Application-Structure/Readme.md | 1 + 21-Hello-World/11-Next-Steps.md | 1 + mdbook/Preface.md | 2 +- packages.dhall | 2 +- 7 files changed, 37 insertions(+), 5 deletions(-) create mode 100644 03-Build-Tools/05-Formatters.md diff --git a/.procedures/redeploy-book.sh b/.procedures/redeploy-book.sh index da8d12866..f9fdc82e9 100755 --- a/.procedures/redeploy-book.sh +++ b/.procedures/redeploy-book.sh @@ -8,7 +8,7 @@ # - `../purescript-jordans-reference-site/src/Summary-header.md` file exists # Regenerate `mdbook`'s source content -node .procedures/mdbook-toc.js -r "." -o "../purescript-jordans-reference-site/src" -s "Summary-header.md" +node .procedures/mdbook-toc.js -r "." -o "../purescript-jordans-reference-site/src" -s "Summary-header.md" -t ".ci,.git,.github,.procedures,.travis,output,book,mdbook" cd ../purescript-jordans-reference-site diff --git a/01-Getting-Started/04-Install-Guide.md b/01-Getting-Started/04-Install-Guide.md index 8e0ea2b82..42ffae744 100644 --- a/01-Getting-Started/04-Install-Guide.md +++ b/01-Getting-Started/04-Install-Guide.md @@ -14,6 +14,7 @@ Throughout your learning process, it will be helpful to ask others for help. The We'll show how to install the following programs: - `purescript` - the PureScript language & compiler - `spago` - a dependency manager and build tool for PureScript +- (optional) a formatter for PureScript - `parcel` - a build tool for bundling a PureScript application into a multiple JS backends (node, browser, electron) ### Installation @@ -44,14 +45,18 @@ Unlike the manual install, `nvm` properly handles the npm prefix for you. So, yo Once you have installed `npm`, we can use it to install everything in one command: ```bash -npm i -g purescript@0.14.2 spago@0.20.3 parcel +npm i -g purescript@0.14.3 spago@0.20.3 parcel ``` +If you want to install a PureScript formatter, refer to their instructions. The history behind these tools will be covered in the `Build Tools` folder: +- [purs-tidy](https://github.com/natefaubion/purescript-tidy) - A self-contained formatter written in PureScript +- [pose](https://pose.rowtype.yoga/) - A plugin written in PureScript for the [`Prettier`](https://prettier.io/) formatter + ### Versions Used in this Project The following commands should now work (the versions beside them are the versions I used when writing this project): ```bash -purs --version # 0.14.2 +purs --version # 0.14.3 spago version # 0.20.3 parcel --version # 1.12.4 ``` diff --git a/03-Build-Tools/05-Formatters.md b/03-Build-Tools/05-Formatters.md new file mode 100644 index 000000000..36db8db7b --- /dev/null +++ b/03-Build-Tools/05-Formatters.md @@ -0,0 +1,25 @@ +# Formatters + +## History + +For the longest time, PureScript did not have a formatter. There are a number of reasons: +1. Since `PureScript` is written in Haskell, people are less likely to contribute since Haskell is still different from PureScript (even if they share similarities). + 1. Ideally, `PureScript` would be written in PureScript. Unfortunately, if `PureScript` was self-hosted, runtime performance of the `purs` binary would suffer greatly otherwise. See [purescript/purescript-in-purescript](https://github.com/purescript/purescript-in-purescript), which was stopped after that realization was made. + 2. Realistically, a formatter could be written in Haskell and reuse the PureScript language's parser. However, then less people would contribute as not everyone is familiar with Haskell + 3. If a formatter was written in PureScript, it would get more contributions.However, it would have to reimplement the PureScript language's parser and stay in sync with any changes made to the language. Moreover, it would likely be slower than writing it in a lower-level language (e.g. Haskell). +1. Writing a formatter is very hard to do. It's typically a feat not done by your beginner or everyday programmer. +1. Once written, maintainers can burn out because many individuals will want configuration added (e.g. "it should indent A in situation Y exactly N spaces but only M spaces in situation Z"). If the configuration is not added, people complain. If it is added, others might later complain about how it has TOO much configuration. Either way, it's typically the maintainer who adds the feature and those who want it don't contribute. + +The first formatter written was [`purty`](https://gitlab.com/joneshf/purty). This formatter was written in Haskell. It was the only formatter for a number of years. Some in the community chose to use it while others did not. + +Around March/April 2021, `@natefaubion` wrote a PureScript implementation of the PureScript language's parser: [natefaubion/purescript-language-cst-parser](https://github.com/natefaubion/purescript-language-cst-parser). + +The second and third formatters, [`purs-tidy`](https://github.com/natefaubion/purescript-tidy) and [`pose`](https://pose.rowtype.yoga/), respectively, were announced around the same time in August 2021. Both projects were under developement without knowing about each other. `purs-tidy` is a standalone formatter whereas `pose` is a plugin for the [`Prettier` formatter](https://prettier.io/). + +## Current Formatters + +| Formatter | Language | Author | Initial Announcement | +| - | - | - | - | +| [`purs-tidy`](https://github.com/natefaubion/purescript-tidy) | PureScript | `@natefaubion` | [Announcing `purs-tidy`: a syntax tidy-upper for PureScript](https://discourse.purescript.org/t/tiny-announcement-yet-another-purescript-formatter/2525) | +| [`pose`](https://pose.rowtype.yoga/) | PureScript | `@Zelenaya`/`@i-am-the-slime` | [Tiny announcement: yet another PureScript formatter](https://discourse.purescript.org/t/tiny-announcement-yet-another-purescript-formatter/2525) | +| [`purty`](https://gitlab.com/joneshf/purty) | Haskell | `@joneshf` | [Purty 1.0.0 released](https://discourse.purescript.org/t/purty-1-0-0-released/225) | diff --git a/21-Hello-World/05-Application-Structure/Readme.md b/21-Hello-World/05-Application-Structure/Readme.md index cb66ab18f..c19cb95c3 100644 --- a/21-Hello-World/05-Application-Structure/Readme.md +++ b/21-Hello-World/05-Application-Structure/Readme.md @@ -35,6 +35,7 @@ To get a general idea for the concept this folder is going to try to teach: - 'Which code is more reusable' (45:28 - 50:29): - Final Encoding = Provide an implementation as an argument = monad transformers (what we cover first in this folder) - Initial Encoding = Interpret a result = `Free` monad (what we cover second in this folder) +- Optional reading: [Final tagless encodings have little to do with typeclasses](https://www.foxhound.systems/blog/final-tagless/) Another learning resource that is still a work-in-progress but which will explain more than this work is 'Functional Design and Architecture': - [Reddit post introducing it](https://np.reddit.com/r/haskell/comments/avaxda/the_campaign_for_my_book_functional_design_and/?st=jsowhkm4&sh=d2be89c4) diff --git a/21-Hello-World/11-Next-Steps.md b/21-Hello-World/11-Next-Steps.md index 6a1b4f0aa..1338446ed 100644 --- a/21-Hello-World/11-Next-Steps.md +++ b/21-Hello-World/11-Next-Steps.md @@ -30,6 +30,7 @@ The below programs were written by me when I was first learning how to design pr - [jonasbuntinx' - 'Real World App' (React Version)](https://github.com/jonasbuntinx/purescript-react-realworld) - [jaspervdj's 'Beeraffe' game](https://github.com/jaspervdj/beeraffe/) - [AndrewBrownK's 'Minesweeper CLI' game](https://github.com/AndrewBrownK/purescript-minesweeper-cli) +- [`aftok`](https://github.com/aftok/aftok) ### Projects in non-JS backends diff --git a/mdbook/Preface.md b/mdbook/Preface.md index df4250e44..c1c3f4337 100644 --- a/mdbook/Preface.md +++ b/mdbook/Preface.md @@ -14,7 +14,7 @@ If you want to learn PureScript, read the entire work from start to finish. ## Overview and Scope of the Work -All code in this work uses PureScript `0.14.2` +All code in this work uses PureScript `0.14.3` This work was created so a reader can understand PureScript and how to use it properly from a deep foundational understanding. Most other resources will get you started quickly, but then you will get confused at some point along the way. This resource takes longer to get started, but you will either not be confused or be less confused when we get to more advanced topics (e.g. monad transformers, type-level programming, etc.) diff --git a/packages.dhall b/packages.dhall index 00ce6fc4b..9ece26b2f 100644 --- a/packages.dhall +++ b/packages.dhall @@ -1,5 +1,5 @@ let upstream = - https://github.com/purescript/package-sets/releases/download/psc-0.14.2-20210629/packages.dhall sha256:534c490bb73cae75adb5a39871142fd8db5c2d74c90509797a80b8bb0d5c3f7b + https://github.com/purescript/package-sets/releases/download/psc-0.14.3-20210808/packages.dhall sha256:dbc06803c031113d3f9e001f8d95629e48da720d2bfe45d8bbe2c0cffcef293d let additions = { benchotron =