=================
Haskell Formatter
=================

The Haskell Formatter formats Haskell source code. It is strict in that it fundamentally rearranges code.

Installation
============

Run

::

    $ cabal install haskell-formatter

to create an executable, which is referred to as ``haskell-formatter`` in the following. On Linux, for example, you should now be able to call it as

::

    $ ~/.cabal/bin/haskell-formatter --help

In case of issues with dependencies, try to use a Cabal sandbox. For convenience, this can be done by

::

    $ make sandbox

Usage
=====

Basics
------

Read source code from ``Input.hs``, format it, and write it to ``Output.hs`` by

::

    $ haskell-formatter --input Input.hs --output Output.hs

If the input or output file is not given, it defaults to the corresponding standard stream. This allows commands like

::

    $ haskell-formatter < Input.hs

For more help about the usage, call

::

    $ haskell-formatter --help

Style Configuration
-------------------

The formatting style can be configured with a file referred by the ``--style`` option. For instance, the call

::

    $ haskell-formatter --style my_style.yaml --input Input.hs --output Output.hs

uses ``my_style.yaml`` as a style file. Such files are in the `YAML format <http://en.wikipedia.org/wiki/YAML>`_. The following is an `example style file <testsuite/resources/examples/default_style.yaml>`_, which at the same time shows the available keys with their default values.

.. GitHub does currently not allow to include files with the reStructuredText directive ``include`` (https://github.com/github/markup/issues/172).

   Thus, the file content is replicated here. There is a test which checks that the strings of both sources are equal.

.. code:: yaml

    # Lines should be no longer than this length in characters.
    line_length_limit: 80
    
    # How much to spread code over multiple lines instead of trying to fill a single
    # line. More precisely, this guides the ratio of "line_length_limit" to the
    # ribbon length (the number of characters on a line without leading and trailing
    # whitespace). Only the lowest value of 1 forces "line_length_limit" to be
    # applied strictly.
    # Reference: http://citeseerx.ist.psu.edu/viewdoc/summary?doi=10.1.1.38.8777
    ribbons_per_line: 1
    
    # More than this number of empty lines in succession are merged.
    successive_empty_lines_limit: 1
    
    # Indentation lengths in characters.
    indentations:
        class:  8    # "class" and "instance" declarations.
        do:     3    # "do" notation. 
        case:   4    # Body of "case" expressions.
        let:    4    # Declarations in "let" expressions.
        where:  6    # Declarations in "where" clauses.
        onside: 2    # Continuation lines which would otherwise be offside.
    
    # Decides which parts of the code to sort.
    order:
        # Sequence of import declarations.
        import_declarations: true
    
        # Entities of import lists.
        import_entities: true

Related Projects
================

You may like to have a look at the following projects, which aim at formatting Haskell code, too.

* `hindent <https://github.com/chrisdone/hindent>`_
* `stylish-haskell <https://github.com/jaspervdj/stylish-haskell>`_

License
=======

See the `LICENSE file <LICENSE>`_.