wz1000 / brittany

haskell source code formatter

brittany

haskell source code formatter

(see another demonstration in Showcase.md)

This project's goals roughly are to:

• Be idempotent (this also directly ensures that only valid haskell is produced);
• Support the full ghc-haskell syntax including syntactic extensions;
• 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.

At this point, these goals are completed to different degrees. Currently, 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 syntax including extensions, but many of the less common syntactic elements (even of 2010 haskell) are not handled. There are cases where comments are not re-inserted properly (leading to an error or to affected comments being placed at a different location than in the input).

The current algorithm is rather clever about horizontal space while still being linear in the size of the input (although the constant factor is not small).

Important notes

• Requires ghc>=8
• -XCPP is not officially supported (yet).
• Some commandline flags mentioned in the help don't work yet (and won't even be parsed correctly.) (fixed in 0.4.0.0)
• some config values can not be configured via commandline yet.
• Creates a brittany.yaml config file in the current directory. (fixed in 0.5.0.0; now creates user config file in ~/.brittany; still reads brittany.yaml in current dir if present.)
• Currently some unhandled syntactical constructs don't raise errors (fixed in 0.6.0.0)
• 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.)

Installation

• via cabal "old-build"

  git clone https://github.com/lspitzner/brittany.git
  cd brittany
  cabal sandbox init
  cabal install --bindir=$HOME/.cabal/bin # -w $PATH_TO_GHC_8

• via cabal new-build

  git clone https://github.com/lspitzner/brittany.git
  cd brittany
  # cabal new-configure -w $PATH_TO_GHC_8
  cabal new-build brittany
  # and it should be safe to just copy the executable, e.g.
  cp ./dist-newstyle/build/brittany-0.8.0.0/build/brittany/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