spacemacs/layers/+lang/elixir/README.org

#+TITLE: Elixir layer

[[file:img/elixir.png]] with [[file:img/alchemist.png]]

* Table of Contents                                         :TOC_4_gh:noexport:
 - [[#description][Description]]
 - [[#install][Install]]
 - [[#configuration][Configuration]]
   - [[#flycheck][Flycheck]]
     - [[#credo][Credo]]
     - [[#mix-compile][mix compile]]
 - [[#key-bindings][Key bindings]]
   - [[#refcard][Refcard]]
   - [[#help][Help]]
   - [[#mix][Mix]]
   - [[#project][Project]]
   - [[#evaluation-in-place][Evaluation in place]]
   - [[#repl-interactions][REPL interactions]]
   - [[#tests][Tests]]
   - [[#compile][Compile]]
   - [[#execute][Execute]]
   - [[#code-definition-jump][Code Definition Jump]]

* Description
This layer adds support for [[http://elixir-lang.org/][Elixir]] .

[[https://github.com/tonini/alchemist.el][Alchemist]] brings the Elixir tooling to Emacs and comes with a bunch of
features like:
- Powerful IEx integration
- Mix integration
- Compile & Execution of Elixir code
- Inline code evaluation
- Documentation lookup
- Definition lookup
- Smart code completion
- Elixir project management
- Integration with [[http://company-mode.github.io/][company-mode]]
- Flycheck support for mix compile
- Flycheck support for [[https://github.com/rrrene/credo][credo]]
- Flycheck support for test results

* Install
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =elixir= to the existing =dotspacemacs-configuration-layers= list in this
file.

* Configuration
** Flycheck
*Note:* since flycheck checkers are slow, the checks are enabled only at save
time.

*** Credo
A flycheck checker for [[https://github.com/rrrene/credo][credo]] is installed. The check needs both =bunt= and
=credo= to be available, you can install them like this:

#+BEGIN_SRC shell
git clone https://github.com/rrrene/bunt
cd bunt
mix archive.build
mix archive.install
#+END_SRC

#+BEGIN_SRC shell
git clone https://github.com/rrrene/credo
cd credo
mix deps.get
mix archive.build
mix archive.install
#+END_SRC

*** mix compile
*Important:*
Elixir compilation is based on macros and is unsafe since arbitrary code can
be run during compilation. Therefore Spacemacs disable compilation flycheck
support by default.

To enable flycheck support for =mix compile= *globally* the variable
=elixir-enable-compilation-checking= must be explicitly set to =t= in your
dotfile.

It is recommended to use directory local variables instead. These variables are
stored in a file named =.dit-local.el= at the root of your project. Their values
are applied only for the project and not outside. To easily add a directory
local variable used ~SPC f v d~ and provide the mode =elixir-mode= then the
variable name =elixir-enable-compilation-checking= and its value.

Spacemacs marks the variable =elixir-enable-compilation-checking= as safe so
Emacs won't ask you if the variable is safe whenever an elixir file is opened.

Remember that you can check the flycheck checkers enabled with ~SPC e v~.

* Key bindings
** Refcard
You find and overview of all the key-bindings on the [[file:alchemist-refcard.pdf][Alchemist-Refcard]].

** Help

| Key Binding | Description                         |
|-------------+-------------------------------------|
| ~SPC m h :~ | Run custom search for help          |
| ~SPC m h h~ | Show help of the current expression |
| ~SPC m h H~ | Toggle through search history       |
| ~SPC m h r~ | Show help for current region        |

** Mix

| Key Binding | Description                                                |
|-------------+------------------------------------------------------------|
| ~SPC m m :~ | Prompt for a =mix= command                                 |
| ~SPC m m c~ | Compile the whole application                              |
| ~SPC m m h~ | Show help for a specific =mix= command                     |
| ~SPC m m x~ | Run the given expression in the Elixir application context |

** Project

| Key Binding | Description                                                |
|-------------+------------------------------------------------------------|
| ~SPC m p t~ | Open project test directory and list all test files.       |
| ~SPC m g t~ | Toggle between a file and its tests in the current window. |
| ~SPC m g T~ | Toggle between a file and its tests in other window.       |

** Evaluation in place

| Key Binding | Description                             |
|-------------+-----------------------------------------|
| ~SPC m e b~ | Evaluate buffer                         |
| ~SPC m e B~ | Evaluate buffer and insert result       |
| ~SPC m e l~ | Evaluate current line                   |
| ~SPC m e L~ | Evaluate current line and insert result |
| ~SPC m e r~ | Evaluate region                         |
| ~SPC m e R~ | Evaluate region and insert result       |

** REPL interactions

| Key Binding | Description                                                     |
|-------------+-----------------------------------------------------------------|
| ~SPC m s c~ | Compiles the current buffer in the IEx process.                 |
| ~SPC m s i~ | Start an =iex= inferior process                                 |
| ~SPC m s I~ | Start an IEx process with mix (=iex -S mix=)                    |
| ~SPC m s l~ | Send current line to REPL buffer                                |
| ~SPC m s L~ | Send current line to REPL buffer and focus it in =insert state= |
| ~SPC m s m~ | Reloads the module in the current buffer in your IEx process    |
| ~SPC m s r~ | Send region to REPL buffer                                      |
| ~SPC m s R~ | Send region to REPL buffer and focus it in =insert state=       |

** Tests

| Key Binding | Description                           |
|-------------+---------------------------------------|
| ~SPC m g t~ | Open the test file for current buffer |
| ~SPC m t a~ | Run all the tests                     |
| ~SPC m t b~ | Run all the tests from current buffer |
| ~SPC m t r~ | Rerun the last test                   |
| ~SPC m t t~ | Run test under point                  |

** Compile

| Key Binding | Description                                        |
|-------------+----------------------------------------------------|
| ~SPC m c :~ | Run a custom compile command with =elixirc=        |
| ~SPC m c b~ | Compile the current buffer with elixirc. =elixirc= |
| ~SPC m c f~ | Compile the given filename with =elixirc=          |

** Execute

| Key Binding | Description                                |
|-------------+--------------------------------------------|
| ~SPC m x :~ | Run a custom execute command with =elixir= |
| ~SPC m x b~ | Run the current buffer through =elixir=    |
| ~SPC m x f~ | Run =elixir= with the given filename       |

** Code Definition Jump

| Key Binding | Description                                        |
|-------------+----------------------------------------------------|
| ~SPC m g g~ | Jump to the elixir expression definition at point. |
| ~SPC m ​,​~   | Pop back to where ~SPC m g g~ was last invoked.    |