brittany: Haskell source code formatter

[ agpl, language, library, program ] [ Propose Tags ]

See the README.

If you are interested in the implementation, have a look at this document;

The implementation is documented in more detail here.


[Skip to Readme]

Flags

Manual Flags

NameDescriptionDefault
brittany-dev

dev options

Disabled
brittany-dev-lib

set buildable false for anything but lib

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Maintainer's Corner

For package maintainers and hackage trustees

Candidates

Versions [RSS] 0.8.0.2, 0.8.0.3, 0.9.0.0, 0.9.0.1, 0.10.0.0, 0.11.0.0, 0.12.0.0, 0.12.1.0, 0.12.1.1, 0.12.2.0, 0.13.0.0, 0.13.1.0, 0.13.1.1, 0.13.1.2, 0.14.0.0, 0.14.0.1, 0.14.0.2 (info)
Change log ChangeLog.md
Dependencies aeson (>=1.0.1.0 && <1.3), base (>=4.9 && <4.11), brittany, butcher (>=1.1.0.0 && <1.2), bytestring (>=0.10.8.1 && <0.11), cmdargs (>=0.10.14 && <0.11), containers (>=0.5.7.1 && <0.6), czipwith (>=1.0.0.0 && <1.0.1), data-tree-print, deepseq (>=1.4.2.0 && <1.5), directory (>=1.2.6.2 && <1.4), either (>=4.4.1.1 && <4.5), extra (>=1.4.10 && <1.7), filepath (>=1.4.1.0 && <1.5), ghc (>=8.0.1 && <8.3), ghc-boot-th (>=8.0.1 && <8.3), ghc-exactprint (>=0.5.3.0 && <0.6), ghc-paths (>=0.1.0.9 && <0.2), hspec (>=2.4.1 && <2.5), monad-memo (>=0.4.1 && <0.5), mtl (>=2.2.1 && <2.3), multistate (>=0.7.1.1 && <0.8), neat-interpolation (>=0.3.2 && <0.4), pretty (>=1.1.3.3 && <1.2), safe (>=0.3.9 && <0.4), semigroups (>=0.18.2 && <0.19), strict (>=0.3.2 && <0.4), syb (>=0.6 && <0.8), text (>=1.2 && <1.3), transformers (>=0.5.2.0 && <0.6), uniplate (>=1.6.12 && <1.7), unsafe (>=0.0 && <0.1), yaml (>=0.8.18 && <0.9) [details]
License AGPL-3.0-only
Copyright Copyright (C) 2016-2017 Lennart Spitzner
Author Lennart Spitzner
Maintainer Lennart Spitzner <hexagoxel@hexagoxel.de>
Revised Revision 1 made by lspitzner at 2018-04-05T19:03:34Z
Category Language
Home page https://github.com/lspitzner/brittany/
Bug tracker https://github.com/lspitzner/brittany/issues
Source repo head: git clone https://github.com/lspitzner/brittany.git
Uploaded by lspitzner at 2017-09-28T21:26:03Z
Distributions Arch:0.14.0.2, NixOS:0.14.0.2
Executables brittany
Downloads 16550 total (188 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2017-09-28 [all 1 reports]

Readme for brittany-0.8.0.3

[back to package description]

brittany Hackage version Stackage version Build Status

haskell source code formatter

Output sample

(see more examples and comparisons)

This project's goals roughly are to:

  • Always retain the semantics of the source being transformed;
  • Be idempotent (this also directly ensures that only valid haskell is produced);
  • 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 it 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 type-signatures and function/value bindings are processed; other module elements (data-decls, classes, instances, imports/exports 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.)
  • There is an open performance issue on large inputs (due to an accidentally quadratic sub-algorithm); noticable for inputs with >1k loc. (fixed in 0.8.0.3)

Other usage notes

  • Supports GHC versions 8.0.* and 8.2.*.
  • config (file) documentation is lacking.
  • some config values can not be configured via commandline yet.
  • uses/creates user config file in ~/.brittany/config.yaml; also reads brittany.yaml in current dir if present.

Installation

  • via cabal "old-build"

    # optionally:
    # mkdir brittany
    # cd brittany
    # cabal sandbox init
    cabal install brittany --bindir=$HOME/.cabal/bin # -w $PATH_TO_GHC_8_0
    
  • via cabal new-build

    cabal unpack brittany
    cd brittany-0.8.0.2
    # cabal new-configure -w $PATH_TO_GHC_8_0
    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/
    
  • via stack

    git clone https://github.com/lspitzner/brittany.git
    cd brittany
    stack install
    

Usage

  • Currently one mode of operation: Transform a single module. By default read from stdin and written to stdout, but commandline arguments allow to read/write from/to files.

  • For stdin/stdout usage it makes sense to enable certain syntactic extensions by default, i.e. to add something like this to your ~/.brittany/config.yaml (execute brittany once to create default):

    conf_forward:
      options_ghc:
      - -XLambdaCase
      - -XMultiWayIf
      - -XGADTs
      - -XPatternGuards
      - -XViewPatterns
      - -XRecursiveDo
      - -XTupleSections
      - -XExplicitForAll
      - -XImplicitParams
      - -XQuasiQuotes
      - -XTemplateHaskell
      - -XBangPatterns
    

Implementation/High-level Documentation

See the documentation index

License

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/.