Google Summer of Code 2021 Work Product Submission - Emma Bastås

README.md

Google Summer of Code 2021 Work Product Submission

Student: Emma Bastås
Mentor: Aaron VonderHaar
Organization: elm-tooling
Original proposal: elm-tooling/gsoc-projects#13

---

1. Build instructions and binaries

Snapshot binaries for Mac and Linux are available here: https://elm-format.avh4.net/snapshots/new-parser-2021/0.8.5-224-g69ff30df/

To build from source:

1. Install Haskell ghcup following the instructions for your operating system: https://www.haskell.org/ghcup/

# check out the repo
git clone https://github.com/avh4/elm-format.git
cd elm-format

# checkout all code contributed as part of this gsoc project
git checkout 724861e2383ec3a8b0e14bd7f71647ea817aa071

# initial setup
ghcup install ghc 8.10.4
ghcup set ghc 8.10.4

# build
./build.sh -- build

# run the built elm-format
./_build/elm-format

run tests with ./build.sh

1. Overview of work done

The final product of my work are my commits to elm-format:new-parser-2021 that have been merged continuously over the course of this project. There is also an issue with accompanying branch that won't be merged, and some documentation. The subsections splits this work into sections and provides context.

2.1 Parsec adapter API

The primary goal of this project has been to make a parsec-like API that's implemented using parsing primitives from the Elm compiler. The goal being that the dependency on parsec can be removed without having to refactor the entire parsing codebase. This is achieved in the following PRs:

• WIP: Parsec API for the new Elm parser
• Bugfixes and small improvments to the parsec adapter
• Parser API refactor
• Misc refactors to the Elm compiler's parser integration code

2.2 Migrating to Elm compiler-style parsers

After the parsec-like adapter API was implemented focused switched to the secondary goal which has been to migrate parts of the parsing code to use parsers from the Elm compiler directly, instead of using primitives through the adapter API. The entire parsing codebase has not been migrated, but parsing of literals was migrated in the following two PRs:

• Use code from the Elm compiler to parse strings
• Use code from Elm compiler to parse numbers

2.3 Coverage report

Though not stated as an objective in the original project proposal, and not being directly helpful to achieving any of the objectives I decided (after consulting with my mentor) to explore generating coverage reports, mostly out of curiosity. Coverage reports are useful to aspects of elm-format outside the scope of this project, like spotting blind spots in the test suite or dead code. This work is captured in this issue with a short description of the process and link to code.

In the end this work didn't end up being helpfull to the project, but since it bennefits elm-format and I made the work within the timeframe of this project I'm choosing to include it here.

2.4 Documentation

Documentation related to parsing in elm-format and this, now ongoing project of overhauling elm-formats parsing codebase has also been written. It can be found here. The intention is that if someone (including me and my mentor) wants to continue this overhaul at a later date there should be some documentation to point them in the right direction.

3. Goals reached

As defined in the original project proposal the goals have been:

1. elm-format’s parsers uses the parser API from the compiler via the adapter layer instead of parsec and indents.
2. The dependency on parsec and indents can be removed.
3. No new bugs are introduced. Code is relatively clean and maintainable.
4. (optional) Parsers use the new parser API directly of the adapter layer. The adapter layer can be removed.

(1) and (2) are covered in section 2.1 Parsec adapter API.

(3) is quite subjective. elm-format has a pretty extensive test-suite and all of the merged code passes the suite. I'll let my mentor be the judge of whether or not the code is relatively clean and maintainable, what I can say is that care has been taken to improve maintainability through various refactors.

(4) is started but not complete, it's covered in section 2.2 Migrating to Elm compiler-style parsers.

4. Usability of produced code

The code produced is in a state where it compiles and there is confidence that it behaves as expected and it will be included in the next elm-format release. The changes themselves don't warrant their own release since there's no change from the perspective of the end user, instead this code improves maintainability, starts a process of paying of technical debt in the parsing codebase and laying the foundation for other features in the 1.2 milestone.