Module documentation for 0.9.0.0
haskell source code formatter
This project's goals roughly are to:
- Always retain the semantics of the source being transformed;
- Be idempotent;
- Support the full GHC-haskell syntax including syntactic extensions
-XCPPwhich is too hard);
- Retain newlines and comments unmodified;
- Be clever about using the available horizontal space while not overflowing the column maximum if it cannot be avoided;
- Be clever about aligning things horizontally (this can be turned off completely however);
- Have linear complexity in the size of the input.
In theory, the core algorithm inside brittany reaches these goals. It is rather clever about making use of horizontal space while still being linear in the size of the input (although the constant factor is not small). See these examples of clever layouting.
But brittany is not finished yet, and there are some open issues that yet require fixing:
- only the module header (imports/exports), type-signatures and function/value bindings are processed; other module elements (data-decls, classes, instances, etc.) are not transformed in any way; this extends to e.g. bindings inside class instance definitions - they won't be touched (yet).
- By using
ghc-exactprintas the parser, brittany supports full GHC including extensions, but some of the less common syntactic elements (even of 2010 haskell) are not handled.
- There are some known issues regarding handling of in-source comments. There are cases where comments are not copied to the output (this will be detected and the user will get an error); there are other cases where comments are moved slightly; there are also cases where comments result in wonky newline insertion (although this should be a purely aesthetic issue.)
Try without Installing
You can paste haskell code over here to test how it gets formatted by brittany. (Rg. privacy: the server does log the size of the input, but not the full input/output of requests.)
Other usage notes
- Supports GHC versions
- included in stackage with lts>=10.0 (or nightlies dating to >=2017-11-15)
- config (file) documentation is lacking.
- some config values can not be configured via commandline yet.
- uses/creates user config file in
~/.config/brittany/config.yaml; also reads (the first)
brittany.yamlfound in current or parent directories.
~~~~.sh # optionally: # mkdir brittany # cd brittany # cabal sandbox init cabal install brittany --bindir=$HOME/.cabal/bin # -w $PATHTOGHC80 ~~~~
~~~~.sh cabal unpack brittany cd brittany-0.8.0.2 # cabal new-configure -w $PATHTOGHC80 cabal new-build exe:brittany # and it should be safe to just copy the executable, e.g. cp
./find dist-newstyle/build/ -type f -name brittany$HOME/.cabal/bin/ ~~~~
stackusing a sufficiently recent stackage snapshot (dated to >= 2017-11-15)
~~~~.sh stack install brittany # --resolver lts-10.0 ~~~~
(earlier ltss did not include
brittanyyet, but the repo should contain a
stack.yamlthat works with ghc-8.0.)
on ArchLinux via the britanny AUR package using
aura: ~~~~.sh aura -A brittany ~~~~
In this gist
I have described a haskell setup that includes a shortcut to run brittany formatting.
brittany to VSCode formatting API. Thanks to @MaxGabriel.
#### Via HIE
brittany plugin that directly uses the brittany library.
Relevant for any editors that properly support the language-server-protocol.
#### Neovim / Vim 8
The Neoformat plugin comes with support for
brittany built in.
Default mode of operation: Transform a single module, from
stdout. Can pass one or multiple files as input, and there is a flag to override them in place instead of using
stdout(since 0.9.0.0). So:
~~~~ .sh brittany # stdin -> stdout brittany mysource.hs # ./mysource.hs -> stdout brittany --write-mode=inplace .hs # apply formatting to all ./.hs inplace ~~~~
For stdin/stdout usage it makes sense to enable certain syntactic extensions by default, i.e. to add something like this to your
brittanyonce to create default):
~~~~ confforward: optionsghc: - -XLambdaCase - -XMultiWayIf - -XGADTs - -XPatternGuards - -XViewPatterns - -XRecursiveDo - -XTupleSections - -XExplicitForAll - -XImplicitParams - -XQuasiQuotes - -XTemplateHaskell - -XBangPatterns ~~~~
Feature Requests, Contribution, Documentation
This currently is a one-person project in the sense that 90% of the code is written by one person. And (unfortunately) it is not my job to keep improving this project. Please forgive that as a consequence my time to invest on new features is rather limited.
Nonetheless I consider it "in active development" :)
One way of speeding things up is to make your own contributions. There is a good amount of high-level documentation at
Copyright (C) 2016-2017 Lennart Spitzner
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License, version 3, as published by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License along with this program. If not, see http://www.gnu.org/licenses/.
Revision history for brittany
0.10.0.0 -- March 2018
- Implement module/exports/imports layouting (thanks to sniperrifle2004)
- Expose config paths/parsing functions (thanks to Alexey Raga)
- Fix layouting of
- Fix ticked type operator (e.g.
':-) losing tick (#125)
- Fix alignment issue with cases involving operators (#65)
- Fix comments in tuples being dropped (#37)
- Fix comment placements with let-in (#110)
- Fix layouting of
- Layouting changes:
- Align arguments only if it is the same function being called (#128)
- Do not use single-line layout when infix operator expression contains comments (#111)
- New layouting config items:
--import-col: column for import items
--import-as-col: column for the "as" name of a module
lconfig_reformatModulePreamble: controls module/export/import layouting (default True)
lconfig_allowSingleLineExportList: permit one-line module header, e.g.
module Main (main)(default False)
0.9.0.1 -- February 2018
TupleSections(thanks to Matthew Piziak)
- Fix Shebang handling with stdin input (#92)
- Fix bug that effectively deleted strict/lazy matches (BangPatterns) (#116)
- Fix infix operator whitespace bug (#101, #114)
- Fix help command output and its layouting (#103)
- Fix crash when config dir does not exist yet (#115)
- Layouting changes:
- no space after opening non-tuple parenthesis even for multi-line case
- use spaces around infix operators (applies to sections and in pattern matches)
- Let-in is layouted more flexibly in fewer lines, if possible (thanks to Evan Borden)
0.9.0.0 -- December 2017
- Change default global config path (use XDG spec) Existing config should still be respected, so this should not break compatibility
- Support per-project config
- ! Slight rework of the commandline interface:
- Support multiple inputs and outputs
- Support inplace-transformation for multiple files via
IndentPolicyLeft- the indentation mode that never adds more than the base indentation for nested parts (no hanging indentation)
(thanks to Evan Borden)
- Fix bug that manifested in bad output for (top-level) template haskell splices
- Extension support:
- RecursiveDo (was only partially supported previously)
- Layouting Bugfixes:
- Properly reproduce parentheses around kind signatures
- Fix issue around promoted lists
- Trim text from exactprint used as workaround for unknown nodes (unsupported extension workaround)
- Layouting changes
- Insert spaces around operator in sections
0.8.0.3 -- September 2017
- Support for ghc-8.2.1
- Fix quadratic performance issue
- Fix special "where" indentation with indentAmount /= 2
- Fix negative literals in patterns
- Support type applications
--helpand improve help layouting (via butcher-188.8.131.52)
- Add continuous integration via travis (cabal, cabal-new, stack) (brittle due compilation time limit)
- Reduce compilation memory usage a bit
0.8.0.2 -- August 2017
- Add library interface, to be used by
- Publish to hackage.
0.8.0.1 -- May 2017
- Document the high-level design of the program
- Improve layouting for many different cases, too many to list here. Brittany still does only reformat top-level type signatures and bindings.
- Publish all dependencies on hackage;
ghc-exactprintadaptions got merged upstream as well.
- Reduce the aggressiveness of horizontal alignment; this is configurable
lconfig_alignmentBreakOnMultilinevalues (config file only for now).
- (!) Breaking change to the config file format: The keys previously contained
_econf_Werror) but do not anymore (
econf_Werror). Add config version; also
- Move config value
- Cope with unhandled syntactical constructs more gracefully by falling back
on the ghc-exactprint output; Brittany simply won't touch certain
subexpressions instead of aborting. This is further configurable via the
- Due to improvements to the
--key=valueon commandline (only
--key valuewas supported previously).
- Improve testsuite setup: The
tests.bltfile contains many different testcases that allow quick addition - feel free to report bugs directly by making PRs with additions to that file.
- Release under the terms of the AGPLv3
0.7.1.0 -- 2016-09-06
- Support stack
- Fix --ghc-options handling
- Add commandline param to allow shortcut
brittany -i Foo.hs
0.7.0.0 -- 2016-09-04
- First official alpha release
- Fix commandline flag parsing
- Implement/Improve horizontal aligning
- Various minor fixes and layouting improvements
0.6.0.0 -- 2016-08-12
- Add check that output is syntactically valid
- (!) Change config format, breaking previous configs
- Various layouting additions/imporements
- Various minor fixes
0.5.0.0 -- 2016-08-08
- Support --ghc-options
- Support user and local config files: Local config file is not mandatory anymore.
0.4.0.0 -- 2016-08-06
- Make comment handling a bit more clever
- Various layouting additions/imporements
0.3.0.0 -- 2016-08-04
Various layouting additions/imporements
0.2.0.0 -- 2016-07-30
- Basic and partial implementation for expression/decl/statement/pattern layouting
- Prevent exponential behaviour using manual stablenames
0.1.0.0 -- 2016-06-05
- First working code for type signature layouting