tonini/alchemist.el

Elixir Tooling Integration Into Emacs

Alchemist comes with a bunch of features, which are:

• Mix integration
• Compile & Execution of Elixir code
• Inline code evaluation
• Inline macro expanding
• Documentation lookup
• Definition lookup
• Powerful IEx integration
• Smart code completion
• Elixir project management
• Phoenix support
• Integration with company-mode

• Installation
  • Requirements
  • ELPA
  • Via el-get
  • Manual
• Configuration
  • Mix setup
  • IEx setup
  • Execute setup
  • Compile setup
  • Keybindings
  • Testing-Mode
  • Hooks
• Server
• Mix
  • Mix Task Mode
• Testing
• Compile & Execute
  • Compile
  • Execute
• Project
• alchemist-phoenix-mode
• Documentation lookup
  • Keymap
• Definition lookup
  • Symbol definitions
• Auto-completion
• IEx
  • Complete & Documentation lookup
• Eval
• Macroexpand
• Datatype Informations
• Testing Mode
  • Testing-Report
• Modeline
• Keymap
  • Refcards
• Support
• Contributing
• License

Installation

Requirements

• Emacs 24.4 or later
• Elixir 1.0 or later

Installation via package.el

package.el is the built-in package manager in Emacs.

Alchemist.el is available on the three major community maintained repositories - MELPA STABLE, MELPA and Marmalade.

You can install Alchemist with the following command:

M-x package-install [RET] alchemist [RET]

or by adding this bit of Emacs Lisp code to your Emacs initialization file (.emacs or init.el):

(unless (package-installed-p 'alchemist)
  (package-install 'alchemist))

If the installation doesn't work try refreshing the package list:

M-x package-refresh-contents [RET]

Keep in mind that MELPA packages are built automatically from the master branch, meaning bugs might creep in there from time to time. Never-the-less, installing from MELPA is the recommended way of obtaining Alchemist, as the master branch is normally quite stable and "stable" (tagged) builds are released somewhat infrequently.

With the most recent builds of Emacs, you can pin Alchemist to always use MELPA Stable by adding this to your Emacs initialization:

(add-to-list 'package-pinned-packages '(alchemist . "melpa-stable") t)

Via el-get

el-get is another popular package manager for Emacs. If you're an el-get user just do M-x el-get-install [RET] alchemist [RET].

Manual

You can install Alchemist manually by placing Alchemist on your load-path and require ing it. Many people favour the folder ~/.emacs.d/vendor.

(add-to-list 'load-path "~/.emacs.d/vendor/alchemist.el/")
(require 'alchemist)

Configuration

There are some ways Alchemist can be adjusted that certain workflows operating differently.

Mix setup

• Use a different shell command for mix.

(setq alchemist-mix-command "/usr/local/bin/mix")

• Use a different task for running tests.

(setq alchemist-mix-test-task "espec")

• Use custom mix test task options.

(setq alchemist-mix-test-default-options '()) ;; default

• Use a different environment variable in which mix tasks will run.

Mix tasks could always be executed in a specific environment with the usage of C-u (universal-argument). But if you like to change the run of Mix task permanently to a specific environment set it through the variable.

(setq alchemist-mix-env "prod")

IEx setup

• Use a different shell command for iex.

(setq alchemist-iex-program-name "/usr/local/bin/iex") ;; default: iex

Execute setup

• Use a different shell command for elixir.

(setq alchemist-execute-command "/usr/local/bin/elixir") ;; default: elixir

Compile setup

• Use a different shell command for elixirc.

(setq alchemist-compile-command "/usr/local/bin/elixirc") ;; default: elixirc

Modeline setup

• Disable the change of the modeline color with the last test run status.

(setq alchemist-test-status-modeline nil)

Keybindings

• Use a different keybinding prefix than C-c a

(setq alchemist-key-command-prefix (kbd "C-c ,")) ;; default: (kbd "C-c a")

Testing Mode

• Disable the use of a more significant syntax highlighting on functions like test, assert_* and refute_*

(setq alchemist-test-mode-highlight-tests nil) ;; default t

• Don't ask to save changed file buffers before running tests.

(setq alchemist-test-ask-about-save nil)

• Don't change the color of the mode-name when test run failed or passed.

(setq alchemist-test-status-modeline nil)

• Show compilation output in test report.

(setq alchemist-test-display-compilation-output t)

Hooks

• Run the whole test suite with alchemist-mix-test after saving a buffer.

(setq alchemist-hooks-test-on-save t)

• Compile your project with alchemist-mix-compile after saving a buffer.

(setq alchemist-hooks-compile-on-save t)

Server

Alchemist works as a server & client model, where the Alchemist server is written in Elixir and Emacs takes the part of the client.

For each Elixir mix project Alchemist starts an independent server in the background. If an Elixir file gets opened in a buffer, Alchemist checks if a server is running for the current project or not and starts a new one if needed. If there is no Elixir mix project found, Alchemist starts a general unique server.

An Alchemist server can be started/restarted by hand with the call of the function alchemist-server-start. A prompt for the environment in which the server should run (default: dev) gets opened and the server will start/restart in the selected environment.

To get the server status for the current project, just call the function alchemist-server-status and a report will be displayed in the minibuffer:

Alchemist-Server-Status: [Project: /Users/tonini/Projects/ek/ Status: Connected]

Mix

Mix tasks could also be executed in a specific environment with the usage of C-u (universal-argument). Default environments are prod, dev and test. Mix environments

Mix Task Mode

The Mix tasks running in a separate alchemist-mix-mode, in which the following keybindings are available:

Testing

Compile And Execute

Compile functions

Execute functions

Project

alchemist-phoenix-mode

Documentation lookup

There is the alchemist-help-minor-mode for a complete fully functional interface to the Elixir documentation. The alchemist-help-minor-mode uses the same functions like Elixir's IEx.

What does that mean? It means no matter which Elixir version is currently installed on the system, the documentation you get by alchemist is the same IEx would deliver.

Alchemist Help Minor Mode Keymap

Inside of the alchemist-help-minor-mode (*elixir help* buffer) the key ? will open a keymap summary in the minibuffer with the following functionality:

You're always be able to continue to search inside the *elixir help* buffer.

Hit ? to get the keybinding summary for the alchemist-help-minor-mode.

[q]-quit [e]-search-at-point [s]-search [h]-history [?]-keys

Definition lookup

With the function alchemist-goto-definition-at-point, which is bound to M-., you can jump to module and function definitions. If you want to jump back, just use M-, which calls alchemist-goto-jump-back.

You also can jump to the current selected completion candidate with just hit the same key as normally, M-..

By default you're able to jump to definitions of your own mix project codebase and dependencies. But if you would like to also jump to Elixir and Erlang source code you need to tell Alchemist where it can find the source code of Elixir and Erlang.

For that purpose there're two variables you can set:

(setq alchemist-goto-erlang-source-dir "/path/to/erlang/source/")

(setq alchemist-goto-elixir-source-dir "/path/to/elixir/source/")

If you inside an Erlang file and the erlang-mode is enabled you can't use alchemist-goto-jump-back anymore. But if you would like to use it also inside the erlang-mode just setup the following custom hook:

(defun custom-erlang-mode-hook ()
  (define-key erlang-mode-map (kbd "M-,") 'alchemist-goto-jump-back))

(add-hook 'erlang-mode-hook 'custom-erlang-mode-hook)

Symbol definitions

There is the function alchemist-goto-list-symbol-definitions which lets you jump to a specific module, function or macro definitions in the current file.

Auto-completion

Alchemist users are advised to use company-mode to enable auto-completion inside of Elixir source code.

Alchemist enables a company-mode elixir backend by default if company-mode is installed.

There are the same keybindings for documentation lookup and definition opening for the selected candidate available like company-mode provides.

C-h and <f1> for documentation lookup for the current selected candidate. C-w to jump to the definition of the current selected candidate.

IEx

Alchemist provides a REPL buffer, connected to an Elixir IEx subprocess.

To start an IEx process just run M-x alchemist-iex-run

To start an IEx process in the context of an Elixir project (iex -S mix) just run M-x alchemist-iex-project-run

To start a custom IEx process with additional arguments (like: iex --sname custom) just use the universal-argument C-u before run M-x alchemist-iex-run

Complete & Documentation lookup

When Alchemist finds company-mode it enables if for completion inside the IEx process buffer.

Eval

Alchemist comes with the functionality to evaluate code inside the buffer.

Macroexpand

Note

Macroexpand works currently only for Elixir core macros, but why is this?

Macros are lexical: it is impossible to inject code or macros globally. In order to use a macro, you need to explicitly require or import the module that defines the macro.

The Alchemist-Server is currently under development to handle more knowledge about the current context. After that update expanding custom macros will supported too.

But if you like to expand a custom macro in the mean time and you know where it comes from, you can do something like the following with the Alchemist inline evaluation functionality.

As example, select the code and call the alchemist-eval-print-region and you get the macro expansion below.

require Unless # In order to use a macro, you need to explicitly require the module
expr = quote do: Unless.macro_unless(true, IO.puts "this should never be printed")
res  = Macro.expand_once(expr, __ENV__)
IO.puts Macro.to_string(res)
# => if(!true) do
# =>   IO.puts("this should never be printed")
# => end
# => :ok

Datatype Informations

With Elixir v1.2 comes two new IEx helper functions t/1 and i/1.

• Display type docs with t(Module.type) and t(Module.type/arity)
• Prints information about any data type with i/1.

These two helper functions are available now with the following keybindings/functions.

Testing Mode

Alchemist comes with an minor mode for testing which will be enabled by default inside *_test.exs files.

Testing Report

The tests are reported in the alchemist-test-report-mode, which have the following keybindings:

Keymap

Alchemist comes with a default keymap.

The the default prefix keybinding is C-c a

Refcards

You find and overview of all the key-bindings on the Alchemist-Refcard.

There is also a refcard for usage inside Emacs, which gets dynamically generated with the current adjusted keybindings. If you use the keybinding i on a specific row, it will call describe-function on that function.

Just M-x alchemist-refcard RET

Support

If you hit any problems, please first ensure that you are using the latest version of this code, and that you have updated your packages to the most recent available versions.

• To report bugs or feature requests: please use the issue tracker on Github.
• To talk about the project with people in real time: please join the #emacs-elixir channel on IRC or the #emacs channel on Elixir Slack.

Contributing

We appreciate any contribution to Alchemist, so check out our Contribution guidelines for more information.

License

Copyright © 2014-2015 Samuel Tonini and contributors.

Distributed under the GNU General Public License, version 3