From 0b7d784cd61b96079558adde1cacee05b598abaf Mon Sep 17 00:00:00 2001 From: mrkkrp Date: Fri, 10 May 2019 16:36:51 +0200 Subject: [PATCH] Update the readme file [skip ci] --- README.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 83 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b06b04e..3c06118 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,90 @@ [![CircleCI](https://circleci.com/gh/tweag/ormolu/tree/master.svg?style=svg&circle-token=cfd37a39265561eb44e608f97cf953cb2a394c03)](https://circleci.com/gh/tweag/ormolu/tree/master) -Ormolu is a formatter for Haskell source code. +Ormolu is a formatter for Haskell source code. The projects was created with +the following features in mind: + +* Using GHC's own parser to avoid parsing problems caused by + [`haskell-src-exts`][haskell-src-exts]. +* Writing code is such a way so it's easy to modify and maintain. Roughly, + it means that the project follows the path of [`hindent`][hindent] and is + very much about printing AST in a particular way. +* Implementing one “true” formatting style which admits no configuration. +* Let layout of input source code control layout choices in output. This + means that the choices between single-line/multi-line layouts in each + particular situation are made by user, not by an algorithm. This makes the + implementation simpler and leaves just enough control to the user while + still guaranteeing that the formatted code is stylistically consistent. +* Idempotency: formatting already formatted code doesn't change it. +* Be well-tested and robust to the point that it can be used in large + projects without exposing unfortunate, disappointing bugs here and there. +* The project is commercially backed by a company, that is, Tweag. This + guarantees that it'll be actively maintained and bugs will be fixed. + +## Contribution + +Issues (bugs, feature requests or otherwise feedback) may be reported in +[the GitHub issue tracker for this +project](https://github.com/tweag/ormolu/issues). Pull requests are also +welcome. + +### What to hack on? + +Right now there are two options for people who want to contribute: + +* Implementing rendering of AST. This is the main focus right now because we + want to have a MVP which can render all syntactical constructions found in + Haskell source code. Once that is achieved we'll polish the tool + iteratively. +* [Fixing bugs][bugs]. If this seems more interesting than implementing + rendering of AST, you are welcome to do this as well. + +### Implementing rendering of AST + +The `Ormolu.Printer.Combinators` module provides a DSL for rendering of GHC +AST. You'll probably only need this one module for writing new rendering +functions. The module documents how to use the printing combinators it +provides, consult the Haddocks to learn more about that. + +Create new modules corresponding to the things you want to render under +`Ormolu.Printer.Meat`. For example, there are `Ormolu.Printer.Meat.Type` and +`Ormolu.Printer.Meat.Declaration.Data`. + +Concrete rendering functions get their names by appending `p_` to record +field name which contains the part of AST of interest. For example, types +are often found in fields named `hsType`, so the function for rendering +types is correspondingly: + +```haskell +p_hsType :: HsType GhcPs -> R () +``` + +In general rendering functions like this take 1 or more arguments and +produce `R ()` which is a rendering action. + +### Testing + +Testing has been taken good care of and now it amounts to just adding +examples under `data/examples`. Each example is a pair of files: +`.hs` for input and `-out.hs` for corresponding +expected output. + +Testing is performed as following: + +* Given snippet of source code is parsed and pretty-printed. +* The result of printing is parsed back again and the AST is compared to the + AST obtained from the original file. They should match. +* The output of printer is checked against the expected output. +* Idempotency property is verified: formatting already formatted code + results in exactly the same output. + +Examples can be organized in sub-directories, see the existing ones for +inspiration. ## License Copyright © 2018–2019 Tweag I/O + +[haskell-src-exts]: https://hackage.haskell.org/package/haskell-src-exts +[hindent]: https://hackage.haskell.org/package/hindent +[bugs]: https://github.com/tweag/ormolu/issues?q=is%3Aissue+is%3Aopen+label%3Abug