git.iko.soy/ormolu
on master help sign in
ormolu/README.md
181 lines 5.9 kB history raw
1# Ormolu
3[![License BSD3](https://img.shields.io/badge/license-BSD3-brightgreen.svg)](http://opensource.org/licenses/BSD-3-Clause)
4[![Hackage](https://img.shields.io/hackage/v/ormolu.svg?style=flat)](https://hackage.haskell.org/package/ormolu)
5[![Stackage Nightly](http://stackage.org/package/ormolu/badge/nightly)](http://stackage.org/nightly/package/ormolu)
6[![Stackage LTS](http://stackage.org/package/ormolu/badge/lts)](http://stackage.org/lts/package/ormolu)
7[![Build status](https://badge.buildkite.com/8e3b0951f3652b77e1c422b361904136a539b0522029156354.svg?branch=master)](https://buildkite.com/tweag-1/ormolu)
9Ormolu is a formatter for Haskell source code. The project was created with
10the following goals in mind:
12* Using GHC's own parser to avoid parsing problems caused by
13 [`haskell-src-exts`][haskell-src-exts].
14* Let some whitespace be programmable. The layout of the input influences
15 the layout choices in the output. This means that the choices between
16 single-line/multi-line layouts in each particular situation are made by
17 the user, not by an algorithm. This makes the implementation simpler and
18 leaves some control to the user while still guaranteeing that the
19 formatted code is stylistically consistent.
20* Writing code in such a way so it's easy to modify and maintain.
21* Implementing one “true” formatting style which admits no configuration.
22* That formatting style aims to result in minimal diffs while still
23 remaining very close to “conventional” Haskell formatting people use.
24* Choose a style compatible with modern dialects of Haskell. As new Haskell
25 extensions enter broad use, we may change the style to accommodate them.
26* Idempotence: formatting already formatted code doesn't change it.
27* Be well-tested and robust to the point that it can be used in large
28 projects without exposing unfortunate, disappointing bugs here and there.
30## Building
32The easiest way to build the project is with Nix:
34```console
35$ nix-build -A ormolu
36```
38Or with `cabal-install` from the Nix shell:
40```console
41$ nix-shell --run "cabal new-build"
42```
44Alternatively, `stack` could be used with a `stack.yaml` file as follows.
46```console
47$ cat stack.yaml
48resolver: lts-16.0
49packages:
50- '.'
52$ stack build # to build
53$ stack install # to install
54```
56To use Ormolu directly from GitHub with Nix, this snippet may come in handy:
58```nix
59# This overlay adds Ormolu straight from GitHub.
60self: super:
62let source = super.fetchFromGitHub {
63 owner = "tweag";
64 repo = "ormolu";
65 rev = "de279d80122b287374d4ed87c7b630db1f157642"; # update as necessary
66 sha256 = "0qrxfk62ww6b60ha9sqcgl4nb2n5fhf66a65wszjngwkybwlzmrv"; # as well
67 };
68 ormolu = import source { pkgs = self; };
69in {
70 haskell = super.haskell // {
71 packages = super.haskell.packages // {
72 "${ormolu.ormoluCompiler}" = super.haskell.packages.${ormolu.ormoluCompiler}.override {
73 overrides = ormolu.ormoluOverlay;
74 };
75 };
76 };
78```
80## Usage
82The following will print the formatted output to the standard output.
84```console
85$ ormolu Module.hs
86```
88Add `--mode inplace` to replace the contents of the input file with the
89formatted output.
91```console
92$ ormolu --mode inplace Module.hs
93```
95Use `find` to format a tree recursively:
97```console
98$ ormolu --mode inplace $(find . -name '*.hs')
99```
101## Magic comments
103Ormolu understands two magic comments:
105```haskell
106{- ORMOLU_DISABLE -}
107```
109and
111```haskell
112{- ORMOLU_ENABLE -}
113```
115This allows us to disable formatting selectively for code between these
116markers or disable it for the entire file. To achieve the latter, just put
117`{- ORMOLU_DISABLE -}` at the very top. Note that the source code should
118still be parseable even without the “excluded” part. Because of that the
119magic comments cannot be placed arbitrary, but should rather enclose
120independent top-level definitions.
122## Current limitations
124* CPP support is experimental. CPP is virtually impossible to handle
125 correctly, so we process them as a sort of unchangeable snippets. This
126 works only in simple cases when CPP conditionals surround top-level
127 declarations. See the [CPP][design-cpp] section in the design notes for
128 a discussion of the dangers.
129* Input modules should be parsable by Haddock, which is a bit stricter
130 criterion than just being valid Haskell modules.
131* Various minor idempotence issues, most of them are related to comments.
133## Running on Hackage
135It's possible to try Ormolu on arbitrary packages from Hackage. For that
136execute (from the root of the cloned repo):
138```console
139$ nix-build -A hackage.<package>
140```
142Then inspect `result/log.txt` for possible problems. The derivation will
143also contain formatted `.hs` files for inspection and original inputs with
144`.hs-original` extension (those are with CPP dropped, exactly what is fed
145into Ormolu).
147## Editor integration
149We know of the following editor integrations:
151* [Emacs][emacs-package]
152* [VS Code][vs-code-plugin]
153* vim: [neoformat][neoformat], [vim-ormolu][vim-ormolu]
155## Arch Linux
157To install Ormolu on Arch Linux, one can use [the package on AUR][aur]:
159```console
160yay -S ormolu
161```
163## Contributing
165See [CONTRIBUTING.md][contributing].
167## License
169See [LICENSE.md][license].
171Copyright © 2018–present Tweag I/O
173[design-cpp]: https://github.com/tweag/ormolu/blob/master/DESIGN.md#cpp
174[contributing]: https://github.com/tweag/ormolu/blob/master/CONTRIBUTING.md
175[license]: https://github.com/tweag/ormolu/blob/master/LICENSE.md
176[haskell-src-exts]: https://hackage.haskell.org/package/haskell-src-exts
177[emacs-package]: https://github.com/vyorkin/ormolu.el
178[vs-code-plugin]: https://marketplace.visualstudio.com/items?itemName=sjurmillidahl.ormolu-vscode
179[vim-ormolu]: https://github.com/sdiehl/vim-ormolu
180[neoformat]: https://github.com/sbdchd/neoformat
181[aur]: https://aur.archlinux.org/packages/ormolu