2018-11-25 16:34:28 +03:00
|
|
|
|
# Ormolu
|
|
|
|
|
|
2019-08-31 21:31:55 +03:00
|
|
|
|
[![License BSD3](https://img.shields.io/badge/license-BSD3-brightgreen.svg)](http://opensource.org/licenses/BSD-3-Clause)
|
|
|
|
|
[![Hackage](https://img.shields.io/hackage/v/ormolu.svg?style=flat)](https://hackage.haskell.org/package/ormolu)
|
|
|
|
|
[![Stackage Nightly](http://stackage.org/package/ormolu/badge/nightly)](http://stackage.org/nightly/package/ormolu)
|
|
|
|
|
[![Stackage LTS](http://stackage.org/package/ormolu/badge/lts)](http://stackage.org/lts/package/ormolu)
|
2020-02-10 16:46:13 +03:00
|
|
|
|
[![Build status](https://badge.buildkite.com/8e3b0951f3652b77e1c422b361904136a539b0522029156354.svg?branch=master)](https://buildkite.com/tweag-1/ormolu)
|
2018-11-25 17:09:03 +03:00
|
|
|
|
|
2019-07-02 22:29:07 +03:00
|
|
|
|
Ormolu is a formatter for Haskell source code. The project was created with
|
2019-08-04 22:20:30 +03:00
|
|
|
|
the following goals in mind:
|
2019-05-10 17:36:51 +03:00
|
|
|
|
|
|
|
|
|
* Using GHC's own parser to avoid parsing problems caused by
|
|
|
|
|
[`haskell-src-exts`][haskell-src-exts].
|
2019-10-04 12:30:49 +03:00
|
|
|
|
* Let some whitespace be programmable. The layout of the input influences
|
|
|
|
|
the layout choices in the output. This means that the choices between
|
|
|
|
|
single-line/multi-line layouts in each particular situation are made by
|
|
|
|
|
the user, not by an algorithm. This makes the implementation simpler and
|
|
|
|
|
leaves some control to the user while still guaranteeing that the
|
|
|
|
|
formatted code is stylistically consistent.
|
|
|
|
|
* Writing code in such a way so it's easy to modify and maintain.
|
2019-05-10 17:36:51 +03:00
|
|
|
|
* Implementing one “true” formatting style which admits no configuration.
|
2019-05-17 13:18:01 +03:00
|
|
|
|
* That formatting style aims to result in minimal diffs while still
|
|
|
|
|
remaining very close to “conventional” Haskell formatting people use.
|
2019-10-04 12:30:49 +03:00
|
|
|
|
* Choose a style compatible with modern dialects of Haskell. As new Haskell
|
|
|
|
|
extensions enter broad use, we may change the style to accomodate them.
|
|
|
|
|
* Idempotence: formatting already formatted code doesn't change it.
|
2019-05-10 17:36:51 +03:00
|
|
|
|
* Be well-tested and robust to the point that it can be used in large
|
|
|
|
|
projects without exposing unfortunate, disappointing bugs here and there.
|
|
|
|
|
|
2019-05-30 14:56:42 +03:00
|
|
|
|
## Building
|
|
|
|
|
|
2019-05-31 15:37:41 +03:00
|
|
|
|
The easiest way to build the project is with Nix:
|
2019-05-30 14:56:42 +03:00
|
|
|
|
|
2019-05-31 15:37:41 +03:00
|
|
|
|
```console
|
2019-09-11 10:35:05 +03:00
|
|
|
|
$ nix-build -A ormolu
|
2019-05-31 15:37:41 +03:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Or with `cabal-install` from the Nix shell:
|
|
|
|
|
|
|
|
|
|
```console
|
|
|
|
|
$ nix-shell --run "cabal new-build"
|
2019-05-30 14:56:42 +03:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Alternatively, `stack` could be used with a `stack.yaml` file as follows.
|
2019-05-31 15:37:41 +03:00
|
|
|
|
|
|
|
|
|
```console
|
2019-05-30 14:56:42 +03:00
|
|
|
|
$ cat stack.yaml
|
2019-08-28 15:15:35 +03:00
|
|
|
|
resolver: lts-14.3
|
2019-05-30 14:56:42 +03:00
|
|
|
|
packages:
|
|
|
|
|
- '.'
|
2019-05-30 15:19:03 +03:00
|
|
|
|
|
|
|
|
|
$ stack build
|
2019-05-30 14:56:42 +03:00
|
|
|
|
```
|
|
|
|
|
|
2019-10-04 12:30:49 +03:00
|
|
|
|
To use Ormolu directly from GitHub with Nix, this snippet may come in handy:
|
2019-09-11 13:12:32 +03:00
|
|
|
|
|
|
|
|
|
```nix
|
|
|
|
|
# This overlay adds Ormolu straight from GitHub.
|
|
|
|
|
self: super:
|
|
|
|
|
|
|
|
|
|
let source = super.fetchFromGitHub {
|
|
|
|
|
owner = "tweag";
|
|
|
|
|
repo = "ormolu";
|
|
|
|
|
rev = "de279d80122b287374d4ed87c7b630db1f157642"; # update as necessary
|
|
|
|
|
sha256 = "0qrxfk62ww6b60ha9sqcgl4nb2n5fhf66a65wszjngwkybwlzmrv"; # as well
|
|
|
|
|
};
|
|
|
|
|
ormolu = import source { pkgs = self; };
|
|
|
|
|
in {
|
|
|
|
|
haskell = super.haskell // {
|
|
|
|
|
packages = super.haskell.packages // {
|
|
|
|
|
"${ormolu.ormoluCompiler}" = super.haskell.packages.${ormolu.ormoluCompiler}.override {
|
|
|
|
|
overrides = ormolu.ormoluOverlay;
|
|
|
|
|
};
|
|
|
|
|
};
|
|
|
|
|
};
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2019-05-30 14:56:42 +03:00
|
|
|
|
## Usage
|
|
|
|
|
|
|
|
|
|
The following will print the formatted output to the standard output.
|
2019-05-31 15:37:41 +03:00
|
|
|
|
|
|
|
|
|
```console
|
2019-05-30 14:56:42 +03:00
|
|
|
|
$ ormolu Module.hs
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Add `--mode inplace` to replace the contents of the input file with the
|
|
|
|
|
formatted output.
|
2019-05-31 15:37:41 +03:00
|
|
|
|
|
|
|
|
|
```console
|
2019-05-30 14:56:42 +03:00
|
|
|
|
$ ormolu --mode inplace Module.hs
|
|
|
|
|
```
|
|
|
|
|
|
2019-08-28 16:01:58 +03:00
|
|
|
|
## Current limitations
|
|
|
|
|
|
|
|
|
|
* Does not handle CPP (wontfix, see [the design document][design]).
|
2019-09-17 14:16:47 +03:00
|
|
|
|
* Input modules should be parsable by Haddock, which is a bit stricter
|
2019-10-04 12:30:49 +03:00
|
|
|
|
criterion than just being valid Haskell modules.
|
|
|
|
|
* Various minor idempotence issues, most of them are related to comments.
|
2019-08-28 16:01:58 +03:00
|
|
|
|
|
2019-08-17 00:23:58 +03:00
|
|
|
|
## Editor integration
|
|
|
|
|
|
|
|
|
|
We know of the following editor integrations:
|
|
|
|
|
|
2019-10-18 17:21:31 +03:00
|
|
|
|
* [Emacs][emacs-package]
|
2019-10-22 22:58:57 +03:00
|
|
|
|
* [VS Code][vs-code-plugin]
|
2020-02-18 14:22:03 +03:00
|
|
|
|
* [vim][vim-integration]
|
2019-08-17 00:23:58 +03:00
|
|
|
|
|
2019-07-14 02:01:02 +03:00
|
|
|
|
## Running on Hackage
|
|
|
|
|
|
|
|
|
|
It's possible to try Ormolu on arbitrary packages from Hackage. For that
|
2019-10-04 12:30:49 +03:00
|
|
|
|
execute (from the root of the cloned repo):
|
2019-07-14 02:01:02 +03:00
|
|
|
|
|
|
|
|
|
```console
|
|
|
|
|
$ nix-build -A hackage.<package>
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Then inspect `result/log.txt` for possible problems. The derivation will
|
2019-07-14 13:24:35 +03:00
|
|
|
|
also contain formatted `.hs` files for inspection and original inputs with
|
|
|
|
|
`.hs-original` extension (those are with CPP dropped, exactly what is fed
|
|
|
|
|
into Ormolu).
|
2019-07-14 02:01:02 +03:00
|
|
|
|
|
2019-05-31 16:27:42 +03:00
|
|
|
|
## Contributing
|
2019-05-10 17:36:51 +03:00
|
|
|
|
|
2019-10-22 22:58:57 +03:00
|
|
|
|
See [CONTRIBUTING.md][contributing].
|
2018-11-25 16:34:28 +03:00
|
|
|
|
|
|
|
|
|
## License
|
|
|
|
|
|
2019-10-22 22:58:57 +03:00
|
|
|
|
See [LICENSE.md][license].
|
2019-05-23 16:58:07 +03:00
|
|
|
|
|
2019-07-02 22:27:45 +03:00
|
|
|
|
Copyright © 2018–present Tweag I/O
|
2019-05-10 17:36:51 +03:00
|
|
|
|
|
2019-10-22 22:58:57 +03:00
|
|
|
|
[design]: https://github.com/tweag/ormolu/blob/master/DESIGN.md#cpp
|
|
|
|
|
[contributing]: https://github.com/tweag/ormolu/blob/master/CONTRIBUTING.md
|
|
|
|
|
[license]: https://github.com/tweag/ormolu/blob/master/LICENSE.md
|
2019-05-10 17:36:51 +03:00
|
|
|
|
[haskell-src-exts]: https://hackage.haskell.org/package/haskell-src-exts
|
2019-08-17 00:23:58 +03:00
|
|
|
|
[emacs-package]: https://github.com/vyorkin/ormolu.el
|
2019-10-22 22:58:57 +03:00
|
|
|
|
[vs-code-plugin]: https://marketplace.visualstudio.com/items?itemName=sjurmillidahl.ormolu-vscode
|
2020-02-18 14:22:03 +03:00
|
|
|
|
[vim-integration]: https://github.com/sdiehl/vim-ormolu
|