# elm-mode

Elm mode for Emacs.

## Features

1. Syntax highlighting.
1. Intelligent indentation.
1. Integration with [elm-make](https://github.com/elm-lang/elm-make).
1. Integration with [elm-repl](https://github.com/elm-lang/elm-repl).
1. Integration with [elm-reactor](https://github.com/elm-lang/elm-reactor).
1. Integration with [elm-package](https://github.com/elm-lang/elm-package).
1. Integration with [elm-oracle][elm-oracle]
1. Integration with [elm-format][elm-format]
1. Integration with [elm-test][elm-test]

## Indentation

`elm-mode` indentation is based on cycling: every time you insert a new
line there will be one or more indentation levels available for you to
choose from. The exact number is printed in the minibuffer either as
`Sole indentation` or `Indent cycle (n)...` where `n` is the number of
available indentations to choose from. If the automatic indentation
level was not the one you expected simply hit `TAB` to cycle through the
list (note that hitting any other key will cancel the cycle).

## Installation

### MELPA

If your Emacs has `package.el` (which is automatically the case
for Emacs >= 24), you can install `elm-mode` from the package in
[MELPA](http://melpa.milkbox.net/).

### From source

Add this repo to your load-path and `(require 'elm-mode)`. Ensure that
the following dependencies are available:

* [f](https://github.com/rejeep/f.el)
* [let-alist](https://elpa.gnu.org/packages/let-alist.html)
* [s](https://github.com/magnars/s.el)

This package assumes you are runing Emacs 24 or later.

## Bindings

The following bindings are available in `elm-mode`:

#### `TAGS`

| Keybinding             | Description                                                         |
| ---------------------- | ------------------------------------------------------------------- |
| C-c M-t     | Generate a TAGS file for the current project.                       |
| C-c .       | Jump to tag at point.                                               |
| C-c ,       | Jump to previous location after visiting a tag.                     |

TAGS file generation requires that the UNIX `find`, `egrep` commands
and the Emacs `etags` command be available in your path.

Set or customize `elm-tags-on-save` to `t` to generate a new TAGS file
for the current project on every save.

Set or customize `elm-tags-exclude-elm-stuff` to `nil` to include
source files inside `elm-stuff` directories when generating the TAGS
file.

#### `elm-make`

| Keybinding             | Description                                                                       |
| ---------------------- | --------------------------------------------------------------------------------- |
| C-c C-c     | Compile the current buffer.                                                       |
| C-u C-c C-c | Compile the current buffer, specifying the output file.                           |
| C-c M-c     | Compile the main elm file.                                           |
| C-u C-c M-c | Compile the main elm file, specifying the output file.               |
| C-c C-a     | Add missing type annotations to the current buffer.                               |
| C-u C-c C-a | Add missing type annotations to the current buffer, prompting before each change. |
| C-c C-r     | Clean up imports in the current buffer.                                           |
| C-u C-c C-r | Clean up imports in the current buffer, prompting before each change.             |

#### `elm-repl`

| Keybinding         | Description                                                            |
| ------------------ | ---------------------------------------------------------------------- |
| C-c C-l | Load the current file in a REPL.                                       |
| C-c C-p | Push the current region to a REPL.                                     |
| C-c C-e | Push the current decl. to a REPL (requires haskell-mode). |

#### `elm-reactor`

| Keybinding             | Description                                                        |
| ---------------------- | ------------------------------------------------------------------ |
| C-c C-n     | Preview the current buffer in a browser.                           |
| C-u C-c C-n | Preview the current buffer in a browser in debug mode.             |
| C-c C-m     | Preview the main elm file in a browser.               |
| C-u C-c C-m | Preview the main elm file in a browser in debug mode. |

#### `elm-package`

| Keybinding             | Description                                                  |
| ---------------------- | ------------------------------------------------------------ |
| C-c C-d     | View a function's documentation in a browser.                |
| C-c C-i     | Import a module from one of the dependencies.                |
| C-c C-s     | Sort the imports in the current file.                        |
| C-c M-k     | Open the package catalog.                                    |
| C-u C-c M-k | Open the package catalog, refreshing the package list first. |

The following bindings are available in the package list buffer:

| Keybinding   | Description                    |
| ------------ | ------------------------------ |
| g | Refresh package list.          |
| n | Next package.                  |
| p | Previous package.              |
| v | View package in browser.       |
| m | Mark package for installation. |
| i | Mark package for installation. |
| u | Unmark package.                |
| x | Install marked packages.       |

Set or customize `elm-sort-imports-on-save` to `t` to apply
`elm-sort-imports` on the current buffer on every save.

#### `elm-oracle`

The following functionality requires [elm-oracle][elm-oracle] to be
installed.  `elm-oracle` does not come with the Elm installer so you
will have to install it manually.

| Keybinding          | Description                                               |
| ------------------- | --------------------------------------------------------- |
| C-c C-t  | Show the type of the function at point in the minibuffer. |
| C-c M-d  | Show the documentation of the function at point.          |

`elm-mode` supports auto-completion through `elm-oracle`.  To
use [company-mode][company] for auto-completion, add the Elm backend
to the backend list:

```elisp
(add-to-list 'company-backends 'company-elm)
```

The Company backend supports `company-quickhelp` to display
documentation snippets for the autocompletion candidates.

Here's a screenshot of `company-mode` in action:

![company-mode](/screenshots/company-mode.png)

#### `elm-format`

The following functionality requires [elm-format][elm-format] to be
installed. `elm-format` does not come with the Elm installer so you
will have to install it manually.

| Keybinding         | Description                              |
| ------------------ | ---------------------------------------- |
| C-c C-f | Automatically format the current buffer. |

Set or customize `elm-format-on-save` to `t` to apply `elm-format` on
the current buffer on every save.

Set or customize `elm-format-elm-version` to change which version of
Elm to format against. Valid options are `0.17` and `0.16`. The
default is `0.17`.

#### `elm-test`

The following functionality requires [elm-test][elm-test] to be
installed.  `elm-test` does not come with the Elm installer so you
will have to install it manually.

| Keybinding         | Description                                 |
| ------------------ | ------------------------------------------- |
| C-c t   | Run the test suite for the current project. |

[company-mode]: http://company-mode.github.io/
[elm-format]: https://github.com/avh4/elm-format#installation-
[elm-oracle]: https://github.com/ElmCast/elm-oracle#installation
[elm-test]: https://github.com/rtfeldman/node-test-runner
