Greetings, I am happy to (finally) announce the first hackage release of brittany, a configurable haskell source code formatter based on ghc-exactprint [2]. https://hackage.haskell.org/package/brittany https://github.com/lspitzner/brittany *Introduction* Brittany aims to nicely layout the code and retain empty lines and comments as they appear in the input. For that it uses a fundamentally different approach (see [7]/theory) than other formatters. The project is not finished, yet it already is usable and produces better results than other formatters in many cases. Of course these words come from its creator, so see for yourself: I have included some examples at the bottom of this mail; see [3] and [4] for some more. I wish to stress that this project will only progress at a very slow speed barring support from the community. I hereby offer to work on this and ask for funding. See the "future" paragraph below. *Changelog* Since the "alpha-release" announced previously [5] the most important changes are: - Release under the AGPL-v3; - Release on hackage; - Make horizontal alignment less aggressive by default (see example [6]); - Add high-level documentation (see [7]). This might be of interest to anyone considering to write a formatter (haskell or even otherwise); - Improve testsuite setup; - Improve layouting in many many cases and fix various bugs; - Add a library interface (this integrates with haskell-ide-engine [8]); Brittany still.. - does not touch anything other than top-level type signatures and bindings (imports, classes, instances, data decls, .. are not modified); - contains some bugs (but it checks its own output for validity and aborts); - does not handle many "uncommon" syntactic constructs/extentions (e.g. arrow notation); In preparation of this release the `butcher` and `czipwith` packages were published on hackage as well. I will cover those in separate announcements. *Building* Brittany currently requires ghc-8.0 (no support for previous ghc versions is planned, but 8.2 will be). Now that this package is on hackage, cabal users should be able to install it directly; stack users will currently have to clone and go from there (a stack.yaml is provided). Detailed building guides for cabal, cabal-new and stack are in the project README. Inclusion in stackage is coming as soon as all dependencies are included. *Known issues* - Bad performance for large inputs (really noticeable at >1k loc). The cause is already determined - quadratic instead of linear complexity in one specific function (see issue #34 [9]). Should be fixable and has high priority. - The config (file) lacks documentation. - Comments are not always reproduced exactly when reformatting. There is a lack of testcases for comments in the testsuite. There is the known case of comments in List/MonadComprehensions that currently breaks idempotency (the comments move further left each roundtrip through brittany) where a solution will most likely involve some non-trivial changes in ghc-exactprint (see [10]). - As mentioned above: only certain module elements are transformed, and not all syntactical constructs are supported. re-layouting of imports, data decls, classes and instances are on the radar, but all require a good amount of work. - CPP is not officially supported. This is mostly a WONTFIX. One can enable it by force, and it works to a degree, but it is relatively easy to find cases where it will break (conditional code not being reformatted, leading to syntax errors and theoretically also to change semantics)). - No fine-grained (per file or even per-function) control/configuration, e.g. it is not yet possible to add some pragma/comment to disable reformatting this one carefully layouted-by-hand function that brittany messes up. - No adaption to ghc-8.2 yet. *Future/Outlook* As far as I can tell brittany already works rather well - I use it all the time, even though I still run into issues from time to time. Still, brittany is not finished (these projects never really are, are they?). Up on my list are ghc-8.2 adaption, fixing the performance bug mentioned above, layouting of data decls, layouting of instances, and controlling behaviour/config via flags in the source (as comments). But implementing new functionality costs a lot of time, even with the DSL used internally: One has to understand the GHC AST (which is not always documented), think of all possible interactions ("do users really use record syntax when having more than one constructor?" "are GADT records a thing?"), write the layouting transformation and test it. I have already invested a good amount of my free time into this project but its scope is too large and I decided to put a limit on my personal investment. This means that barring some form of support from the community I don't see new features being implemented at any certain pace. This leaves the following paths: 1) This project is supported monetarily: I hereby offer to (part-time) work on this provided appropriate funding. I am not sure who exactly might be interested in providing this kind of support - I am no student anymore so GSoC is out of the question. Feel free to contact me on- or off-list if interested. 2) (More) Contributors add tests, report (and maybe fix) bugs and most importantly implement new functionality (layouting for any syntactic constructs of the haskell language not yet supported, etc.) I realize that this is not a trivial project to dive into, and there is a good amount of stuff one has to get familiar with before one can start making use of the abstractions (the DSL) provided. On the other hand, I _think_ that the project source code is relatively well-structured (although in-source comments are really sparse, admittedly) and the high-level (markdown) documentation <strike>will scare everyone away due to their length</strike> will allow understanding the project relatively quickly. 3) The project will progress only rather slowly. Regardless I plan to continue maintaining this project, fix bugs as they come up and also work on expanding functionality when I find the time. *Contributing* In ascending order of involvement, you can contribute by: - Reporting issues, especially instances of bad layouting (especially when it is not a pure matter of opinion); - Add to the testsuite, specifically to the `tests.blt` file of the `littests` test. It contains a large number of tests already, but the coverage is not very good. - If you want to really help implementing more stuff, the high-level docs [7] are the right place to get a rough overview, especially the theory document [11]. I have not documented how to write new layouters yet, so for now I recommend looking at the existing ones, e.g. in `Expr.hs`. -- lennart [1] https://hackage.haskell.org/package/brittany https://github.com/lspitzner/brittany/ [2] https://mpickering.github.io/posts/2015-07-23-ghc-exactprint.html https://hackage.haskell.org/package/ghc-exactprint [3] https://github.com/lspitzner/brittany/blob/da692a4341399390018fb03773e15865d... [4] https://github.com/lspitzner/brittany/tree/master/doc/showcases [5] https://mail.haskell.org/pipermail/haskell-cafe/2016-September/124793.html [6] https://github.com/lspitzner/brittany/blob/da692a4341399390018fb03773e15865d... [7] https://github.com/lspitzner/brittany/blob/master/doc/implementation/index.m... [8] https://github.com/haskell/haskell-ide-engine [9] https://github.com/lspitzner/brittany/issues/34 [10] https://github.com/alanz/ghc-exactprint/issues/53 [11] https://github.com/lspitzner/brittany/blob/master/doc/implementation/theory.... -- some layouting examples - would be (re)produced in exactly this way by brittany:
main = do
now <- getCurrentTime let (_, _, week) = toWeekDate . utctDay $ now putStrLn $ ("it's "++) $ case week of 6 -> "the weekend" 7 -> "the weekend" _ -> "a weekday"
localtime <- utcToLocalZonedTime now let hr = todHour . localTimeOfDay . zonedTimeToLocalTime $ localtime case hr of _ | hr < 12 -> putStrLn "it's before noon" | otherwise -> putStrLn "it's after noon"
-- Newlines are used sparingly: Only after "do" and when the -- `liftBaseOpDiscard` application would lead to overflowing 80 columns. main :: IO () main = do pool <- createPostgresqlPool (toS databaseConnectionString) 10 initiate $ \chan -> forever $ do flip runDbConn pool $ do makeSureQueueIsFull chan void $ liftBaseOpDiscard (consumeMsgs chan responseQueue Ack) (uncurry processMsg) threadDelay 1000000
-- Alignment of patterns go [] "" = True go [WildCard ] "" = True go (WildCard :rest) (c:cs) = go rest (c : cs) || go (WildCard : rest) cs go (Union globs:rest) cs = any (\glob -> go (glob ++ rest) cs) globs go [] (_:_) = False go (_:_) "" = False