brittany
Haskell source code formatter
https://github.com/lspitzner/brittany/
Version on this page: | 0.12.1.1@rev:2 |
LTS Haskell 19.33: | 0.14.0.2 |
Stackage Nightly 2022-03-17: | 0.14.0.2 |
Latest on Hackage: | 0.14.0.2 |
brittany-0.12.1.1@sha256:b4cfaabb5c14cd1552cbc8a8f57aef667a836b366a22ff9023a91fb877a9d95d,9357
Module documentation for 0.12.1.1
- Language
- Language.Haskell
- Language.Haskell.Brittany
- Language.Haskell
- Paths_brittany
brittany
haskell source code formatter
(see more examples and comparisons)
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
(but excluding
-XCPP
which is too hard); - Retain newlines and comments unmodified;
- Be clever about using the available horizontal space while not overflowing the column maximum unless 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-exactprint
as 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
8.0
,8.2
,8.4
,8.6
. - 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.yaml
found in current or parent directories.
Installation
-
via
stack
stack install brittany # --resolver lts-10.0
If you use an lts that includes brittany this should just work; otherwise you may want to clone the repo and try again (there are several stack.yamls included).
-
via
nix
:nix build -f release.nix # or 'nix-build -f release.nix' nix-env -i ./result
-
via
cabal
Due to constant changes to the cabal UI, I have given up on making sure these instructions work before releases. Please do not expect these instructions to be up-to-date; they may produce incomprehensible error messages, they may be broken otherwise, they may work now but break with the next cabal release. Thanks for your understanding, and feel free to open issues for any problems you encounter. – lennart
If you are using cabal-3.0, using
cabal install brittany --installdir=$HOME/.cabal/bin
might work. Keep in mind that cabal merely puts a symlink to the “store” into the installdir, so you have to re-install if you ever clean your store. On cabal-2.4, trycabal v2-install brittany
. On cabal-2.2 or earlier you might be succesful usingcabal new-build exe:brittany; cp `find dist-newstyle/ -name brittany -type f | xargs -x ls -t | head -n1` $HOME/.cabal/bin/
. Alternatively, you can also use the v1-approach with sandboxes ascabal v1-sandbox init; cabal v1-install brittany --bindir=$HOME/.cabal/bin
.(TODO: These instructions are more confusing than helpful. I am inclined to just remove them.)
-
on ArchLinux via the brittany AUR package using
aura
:aura -A brittany
Editor Integration
Sublime text
In this gist I have described a haskell setup that includes a shortcut to run brittany formatting.
VSCode
This extension
connects commandline brittany
to VSCode formatting API. Thanks to @MaxGabriel.
Via HIE
haskell-ide-engine
includes a 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.
Atom
Atom Beautify supports brittany as a formatter for Haskell. Since the default formatter is set to hindent, you will need to change this setting to brittany, after installing the extension.
Emacs
format-all support brittany as the default formatter for Haskell.
Usage
-
Default mode of operation: Transform a single module, from
stdin
tostdout
. Can pass one or multiple files as input, and there is a flag to override them in place instead of usingstdout
(since 0.9.0.0). So: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
~/.config/brittany/config.yaml
(executebrittany
once to create default):conf_forward: options_ghc: - -XLambdaCase - -XMultiWayIf - -XGADTs - -XPatternGuards - -XViewPatterns - -XRecursiveDo - -XTupleSections - -XExplicitForAll - -XImplicitParams - -XQuasiQuotes - -XTemplateHaskell - -XBangPatterns
Feature Requests, Contribution, Documentation
For a long time this project has had a single maintainer, and as a consequence there have been some mildly large delays for reacting to feature requests and even PRs.
Sorry about that.
The good news is that this project is getting sponsored by PRODA LTD, and two previous contributors, Evan Borden and Taylor Fausak, have agreed on helping with organisational aspects. Thanks!
Still, this project has a long queue of very sensible feature requests, so it may take some time until new ones get our attention. But with the help of the co-maintainers, at least the reaction-times on PRs and the frequency of releases should improve significantly.
If you are interested in making your own contributions, there is a good amount of high-level documentation at
License
Copyright (C) 2016-2019 Lennart Spitzner
Copyright (C) 2019 PRODA LTD
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/.
Changes
Revision history for brittany
0.12.1.1 – December 2019
- Bugfixes:
- Fix layouting regression of record update for many/large fields
- Fix whitespace regression on ExplicitForall notation
(
foo :: forall a . Show a => a -> a
, note the double space) introduced in 0.12. (#264) - Fix roundtripping of type equality constraint
f :: ((~) a b) => a -> b
(#267)
- One experimental feature addition: Turning brace notation semicolons into newlines when formatting (see #270)
0.12.1.0 – September 2019
- Support ghc-8.8
- Support for OverloadedLabels extension (thanks to Evan Rutledge Borden @eborden)
- Support for Implicit Params extension (thanks to pepe iborra @pepeiborra)
- Add flag
--no-user-config
to enable only using manually passed config - Disable the performance test suite by default to prevent spurious failures
on certain CI setups. The github/travis brittany CI still has all tests
enabled. See the
brittany-test-perf
flag in the cabal file. - Bugfixes:
- Fix one wandering-comment bug for let-in expressions
- Fix invalid result for prefix operator pattern matches
- Fix lambda expression with laziness/strictness annotation
- Fix parenthesis handling for infix pattern matches with 3+ arguments
- Changes to layouting behaviour:
- For pattern matching and data/instance definitions, the usage of parenthesis is now “normalized”, i.e. superfluous parens are removed by brittany.
0.12.0.0 – June 2019
- Support for ghc-8.6 (basic support, not necessarily all new syntactic extensions)
- Support -XExplicitNamespaces and -XPatternSynonyms
- Allow a –dry-run sort of operation via flag “-c/–check-mode” (thanks to Doug Beardsley @mightybyte)
- Include file name in errors about unsupported syntax nodes (thanks to @5outh)
- Partially implement layouting class instances: Layouts children, but falls back on ghc-exactprint for the instance head (thanks to Rupert Horlick @ruhatch)
- Implement layouting for type synonyms (thanks to Rupert Horlick @ruhatch)
- Support -XMagicHash, -XUnboxedTuples (thanks to Sergey Vinokurov @sergv)
- Support -XQuasiQuotes (no formatting applied to the splices; they are simply
retained without causing the dreaded “Unknown construct: HsSpliceE{}”)
lconfig_allowHangingQuasiQuotes
controls whether multi-line QuasiQuotes are allowed to start at the end of the current line, or whether they are always placed in new lines.
- Bugfixes:
- Fix rare-case alignment bug with IndentPolicyMultiple (#144)
- Make inline layout config apply to module header (#151)
- Fix unaligned import-hiding layout (#150)
- Fix idempotence violation for comments around if-then-else (#167)
- Fix comments having an effect on far-away parent node’s layout (#159)
- Fix imports of type operators (“symbolic data types”) (thanks to Phil Hazelden @ChickenProp)
- Work around GHC and cabal-install misfeature “.ghc.environment files” that could break brittany in unexpected and hard-to-understand ways
- Stop removing empty lines before
where
keyword in a couple of cases - Fix functions with mixing prefix/infix style causing error (#234)
- Changes to layout:
- Align usage of spaces for record update vs record construction (#126)
- More indentation to import-hiding-paragraph (follow-up to #150 fix)
- Record construction and update now are layouted in the same way (thanks to Evan Rutledge Borden @eborden)
- Stop allowing single-line layout when there are comments between arguments (#214) (thanks to @matt-noonan)
- Various build-instructions and editor integrations
0.11.0.0 – May 2018
-
Support for ghc-8.4
-
Implement inline-config e.g. “– brittany –indent=4”
respects the following comment forms as input:
source comment affected target ====================================================== "-- brittany CONFIG" whole module "-- brittany-next-binding CONFIG" next binding "-- brittany-disable-next-binding" next binding "-- brittany @ myExampleFunc CONFIG" `myExampleFunc`
multiline-comments are supported too, although the specification must still be a single line. E.g.
“{- brittany –columns 50 -}”
CONFIG is either:
- one or more flags in the form of what brittany accepts on the commandline, e.g. “–columns 50”, or
- one or more specifications in the form of what brittany accepts in its config files for the layouting config (a one-line yaml document), e.g. “{ lconfig_cols: 50 }”
-
Implement
IndentPolicyMultiple
(thanks to Bryan Richter @chreekat) Restrict indentation amounts ton * indentAmount
-
Implement
--obfuscate
that replaces non-keyword identifiers with random names -
Do not write files unless there are changes (don’t update modtime) (
--write-mode=inplace
) (#93) -
Bugfixes:
- Fix empty function constraints (
() => IO ()
) (#133) - Fix overflowing columns caused by aligning with surrounding lines for certain complex cases
- Implement hacky workaround for
type instance
s (-XTypeFamilies
) (#89)
- Fix empty function constraints (
-
Layouting changes:
- On default settings, allow single-line module header
module MyModule where
when no exports - Fix one case of non-optimal layouting for if-then-else
- Allow same-line let binding inside do-notation with
IndentPolicyLeft/Multiple
andindentAmount>=4
- On default settings, allow single-line module header
0.10.0.0 – March 2018
- Implement module/exports/imports layouting (thanks to sniperrifle2004)
- Expose config paths/parsing functions (thanks to Alexey Raga)
- Bugfixes:
- Fix layouting of
NOINLINE
pragma - 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:
lconfig_importColumn
/--import-col
: column for import itemslconfig_importAsColumn
/--import-as-col
: column for the “as” name of a modulelconfig_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
- Support
TupleSections
(thanks to Matthew Piziak) - Bugfixes:
- 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
--write-mode=inplace
-
Implement
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:
- RecordWildCards
- RecursiveDo (was only partially supported previously)
-
Layouting Bugfixes:
- Properly reproduce parentheses around kind signatures
- Fix issue around promoted lists
(example good:
'[ 'True]
bad:'['True]
) - 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
- Bugfixes:
- Fix quadratic performance issue
- Fix special “where” indentation with indentAmount /= 2
- Fix negative literals in patterns
- Support type applications
- Accept
-h
for--help
and improve help layouting (via butcher-1.1.0.2) - 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
haskell-ide-engine
. - 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-exactprint
adaptions got merged upstream as well. - Reduce the aggressiveness of horizontal alignment; this is configurable
via the
lconfig_alignmentLimit
andlconfig_alignmentBreakOnMultiline
values (config file only for now). - (!) Breaking change to the config file format: The keys previously contained
underscore (e.g.
_econf_Werror
) but do not anymore (econf_Werror
). Add config version; also - Move config value
conf_errorHandling.econf_CPPMode
toconf_preprocessor.ppconf_CPPMode
. - 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
econf_omit_output_valid_check
config value. - Due to improvements to the
butcher
library: Accept--key=value
on commandline (only--key value
was supported previously). - Improve testsuite setup: The
tests.blt
file 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 Foo.hs
meaningbrittany -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