billbarnhill / alchemist.el Goto Github PK

Elixir Tooling Integration Into Emacs

Alchemist comes with a bunch of features, which are:

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

• Installation
  • ELPA
  • Via el-get
  • Manual
• Configuration
• Mix
• Compile & Execute
  • Compile
  • Execute
• Project
• Documentation lookup
  • Keymap
• Auto-completion
  • Debug
• IEx
  • Complete & Documentation lookup
• Eval
• Hooks
• Modeline
• Keymap
• Contributing

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 commnad:

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)

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].

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)

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

• Disable ansi color formatted documentation:

(setq alchemist-help-ansi-color-docs nil) ;; default: t

• Enable compilation if needed when do documentation lookup or completion on Elixir project current codebase.

(setq alchemist-project-compile-when-needed t) ;; default nil

• The function alchemist-project-toggle-compile-when-needed can also be used to enable/disable compilation on the fly.

• By default, the error output of failed completions will be displayed in a separat buffer.

Example output:

== ALCHEMIST COMPLETION FAILED ==
== OUTPUT BEGIN:
** (CompileError) mix.exs:5: function asdas/0 undefined
    (stdlib) lists.erl:1336: :lists.foreach/2
    (stdlib) erl_eval.erl:657: :erl_eval.do_apply/6

== OUTPUT END:

This behavior can be disabled with set the following variable.

(setq alchemist-complete-debug-mode nil) ;; default t

To setup custom configurations for different Elixir projects, create a .alchemist file in the root of the project.

Example:

{
  "ansi-color-docs": "nil",
  "compile-when-needed": "t"
}

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.

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.

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.

When the keybinding C-d is used on one of the selected completion candidates, a documentation lookup for the candidate will be made and displayed in another window.

The function alchemist-complete-debug-mode can be used to enable/disable the debug mode. When disabled, the error output from the completion will not be displayed.

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

When Alchemist finds company-mode it enables completion inside in IEx process buffer.

Documention lookup inside an IEx process buffer will also be activated.

When the keybinding C-d is used on one of the selected completion candidates, a documentation lookup for the candidate will be made and displayed in another window.

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

There is a after-save-hook called alchemist-hooks--test-on-save which runs the whole elixir test suite via alchemist-mix-test. The alchemist-mix-test will just run if the current buffer is in major elixir-mode.

If you would like to use it just set the alchemist-hooks-test-on-save variable via (setq alchemist-hooks-test-on-save t) or M-x customize-group [RET] alchemist-hooks

By default the status of alchemist-mix-test, alchemist-compile etc will be represented via the colorized mode-name. In our case that will be the elixir-mode.

If you don't like that just set the alchemist-buffer-status-modeline variable via (setq alchemist-buffer-status-modeline nil) or M-x customize-group [RET] alchemist-buffer

Alchemist comes with a default keymap.

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

Contributions are very welcome!

1. Fork alchemist.el
2. Create a topic branch - git checkout -b my_branch
3. Push to your branch - git push origin my_branch
4. Send me a pull-request for your topic branch
5. That's it!

Copyright © 2014-2015 Samuel Tonini and contributors.

Distributed under the GNU General Public License, version 3