Basic workflow for Alchemist.el

It is not a long time ago I’ve started learning Elixir, and along I picked up using emacs, or I should rather say spacemacs which is an heavily configured emacs distribution with focus on vim keybindings.

This article will cover how I use Alchemist.el written by Samuel Tonini to speed up not only my elixir workflow but also the rate at which I am able to learn the Elixir language. I will cover the following 6 usecases which I also consider the most critical.

• Documentation Lookup
• Navigation
• Compiliation and Mix tasks
• Project and Testing
• Execution and Evaluation
• Using IEx REPL

While I would recommend using spacemacs for any newcomer as it comes bundled with various nice emacs libraries like helm that aids with fuzzy finding, the article will be featuring the common shortcuts for alchemist that will work by default in any emacs setup. Note that there is a discussion to change the default (C-c a) shortcut because of emacs conventions, however at the time of writing it is the one that is used.

Documentation Lookup

By far one of the most important things when learning or working with a programming language is to be able to find and read documentation fast. For this problem Alchemist is a perfect fit. It provides us with 3 elisp functions for exactly that purpose.
alchemist-help ( C-c a h h) will prompt us for input, we can write any function and alchemist will connect to iex run h (function we provided) and open the result in a split for us. This is amazing, coupled with the great documentation elixir and elixir projects have we can read about almost any function right in our editor!
alchemist-help-history ( C-c a h i ) is similar to the previous function with the difference it will look through our previous documentation lookups and let us choose from there.
alchemist-help-search-at-point ( C-c a h e ) is probably the most used one. It will locate the function under your cursor and do an alchemist-help on that.

Alchemist also provides us with a bonus function for opening a reference card or cheatcheet of its own functions for emacs. This command is called
alchemist-refcard and can be called with ( C-a a h r )

Navigation

Navigation is always a crucial part of working on any project, in emacs we have projectile which is a great tool thats helps you move through files in a project. Often however we find ourselves in situations where we want to explore a given module or function/macro but are not sure where it is. Or we simply want to move to it without much hassle. This is where alchemist can help greatly with its alchemist-goto-definition-at-point. Bound by default to M-. ( , g g for spacemacs) this function will jump through files to find the function, module or macro definition which is under the cursor. This is awfully helpfull when documentation is not enough (or available) or simply when you want to move to a specific function in your project to modify it.
Go-to-definition is coupled with this function is alchemist-goto-jump-back ( M-, ) ( , , for spacemacs) which jumps you back where you were before, neat right? There are 2 small catches though, first if you want to be able to jump to the elixir source (which you probably do) you have to download the elixir source and put this to your emacs config:
(setq alchemist-goto-elixir-source-dir “/path/to/elixir-source/”)
Secondly jumps will only work for the compiled parts of your project, which brings us to the next part.

Compiliation and Mix tasks

Elixir is a compiled language with a great tool, Mix from the git-go (pun intended).
Wouldn't it be awesome if we could take advantage of Mix from inside our editor? Well alchemist has foreseen that and implemented nice elisp functions to help us do exactly that.
One commonly used mix task is mix compile when run in shell with a mix.exs this task will compile your entire project in a swoop, it is extremely useful. When you are within emacs with alchemist you can use it with alchemist-mix-compile ( C-c a m c ), it will also prompt you with an input for additional options, but most often just hitting enter is enough.
alchemist-mix ( C-c a x ) is the global mix command for alchemist, once used you can type any mix task and alchemist will run it for you. Regarding compilation, sometimes we just want to compile a single file and not the whole project, for this task I find the following 2 commands very usefull alchemist-compile-file ( C-a c f ) and alchemist-compile-this-buffer ( C-a c b) as the names imply the first command will prompt you for a filename and will compile it, while the latter one will compile the current buffer. For the more advanced cases there is also alchemist-compile ( C-a c c ) which will prompt you for a custom compilation command, but frankly up till now I’ve not used it once. Back to mix commands there are one alchemist function which cannot go without saying, it is especially useful for learning and experimentation. That command is alchemist-mix-run ( C-c a m r ) this command will prompt you for a file name and you can run that file in the context of your current mix project (e.g. with all the dependencies and project code). However what you can also do is put the -e parameter and run some code directly, so you can see what some function would do if run.
Last thing to note about mix is that you can use mix help (command) in your shell to get more info for a specific command.

Project and Testing

Most of the time we will find ourselves inside projects right? Thats why alchemist also features quite handy project helpers. And by far my most favorite one is alchemist-project-toggle-file-and-tests (C-c a p s) with it one can toggle between a file and its test file, making work with test files a bliss.
It will also ask to create the appropriate file if you have not.

You can also open the test file in a split with alchemist-project-toggle-file-and-tests-other-window (C-c a p o) or run it with alchemist-project-run-tests-for-current-file (C-c a p t), thats a huge productivity boost!
And you can also find test quickly using the alchemist-project-find-test (C-c a p f). But alchemist does not offer quick find only for tests, you can also search in the lib directory with alchemist-project-find-lib (C-c a p l).

Now for testing we are also given some functions, most notably:
alchemist-mix-test (C-c a t) This is the command you’ll find yourself using a lot, it run your whole testing suite.
alchemist-mix-test-file (C-c a m t f) This will prompt you for input and run the testing file.
alchemist-mix-rerun-last-test (C-c a r) This will run the last test.
alchemist-mix-test-this-buffer (C-c a m t b) This will run the tests on the current buffer.
alchemist-mix-test-at-point (C-c a m t .) And finally this usefull little thing will run only the test your cursor is under.

Personally I find my self almost always running the whole testing suite, as my programs have not been big enough yet, and it really only takes seconds to run the whole thing. But as your project grows I suppose the other commands become more and more relevant.

Execution and Evaluation

Execution is a rather simple concept in alchemist you simply execute some elixir code. We are given 3 functions to do that from within emacs.
alchemist-execute (C-c a e e) This command is essentially equivalent to running elixir in the shell. After using it you need to specify what you want to run (try -h for help).
alchemist-execute-file (C-c a e f) This executes a given file.
alchemist-execute-this-buffer (C-c a e b) This executes current buffer.
To be honest I still have too find a use for the execute commands but I am sure I’ll find them handy at some point.

Evaluation I find more fun, while in principle only execution really gets things done, evaluation will help you in a number of circumstances.
Evaluation will read some code and will produce its output, either in a buffer bellow or as a comment (print) to the right, so for example if you use print evaluation on lets say 4+4 you will see # => 8 on the right after evaluation. All evaluations are under (C-c a v), there are a total of 13 commands however essentially there is just 3 of them, one for evaluating a line, one for a region and one for the whole buffer, then there is one extra. Let me explain, so each of the 3 commands has 4 versions of it, two of them as we explained above are to either evaluate in a new buffer bellow, or to the side with a comment. The next 2 are are the same however instead of evaluating the result they will evaluate the quoted outcome, this has to do with elixir meta-programming and can be used to get a better understanding of a macro. Finally that extra command is to close the popup if you decide to open the evaluation in a new window/buffer. So try evaluating 3 * 4 + 1 and lets see what you get ;) .
Evaluation can be quite useful, one can use it when teaching someone about elixir to quickly generate output, or you can use it while writing documentation to quickly output what would be expected when running a function.

Using IEx REPL

Now lets talk about the Elixir REPL, as we said before elixir provides us with great tooling, one of the tools elixir comes with is a REPL called iex.
In case you already don’t know, a repl is a tool that lets you write code in a shell like environment and evaluate it instantly. You can try it out by writing iex in your shell. When you start the repl, elixir will include the IEx.Helpers module. This module provides you with a number of quite useful functions.
Most notable I would say are the h/0,1 r/1 functions. If you remember we already talked about the h function in the documentation lookup. Basically with no argument it will provide general iex help, and with one argument it will provide help for the module/function in the argument. The r function will reload a given module. There is also c to compile but you have to provide a file path.

As you might expect alchemist has iex integration. Let’s explore that a bit.
There are a total of 8 elisp functions for iex,
alchemist-iex-run (C-c a i i) This will simply start iex in a new window.
alchemist-iex-project-run (C-c a i p) This will start your mix project in an iex meaning it will compile all your dependencies and libraries, I think I dont have to persuade you of how useful this is.

The following two should be pretty self explanatory by now,
alchemist-iex-send-current-line (C-c a i l)
alchemist-iex-send-region (C-c a i r)
They also come with a go_to variant that will send the code for evaluation and jump to the repl.

alchemist-iex-compile-this-buffer (C-c a i b) Compliles he whole buffer to the repl.
alchemist-iex-reload-module (C-c a i R) Complies and reload the module your cursor is in.

If you have come to Elixir from the Ruby world you probably have experience with pry, and you will be delighted to know that Elixir has a tool exactly like this. Meet IEx.pry. To use it require IEx, put IEx.pry in your code and run your project through iex, e.g. iex -S mix phoenix.server.
Now you can use the iex repl at the specific point in your code, having all your local bindings, you can experiment with code or inspect data,
awesome right?

Sum up

We explored what is by my opinion roughly all cases of alchemist for a begginer Elixir developer. By far the most used will be Documentation Lookup and Navigation, so don’t shy away from them, the faster you become comfortable using them the better. Compilation is something you have to do regardless so its nice we have that functionality right in our editor. Test helpers will make things a faster and let you focus on the code. So use them often (and please write tests). Finally Evaluation, Execution and IEx are really useful for experimentation and understanding our code.

How do you use Alchemist.el? Do you have any specific use cases I did not mention? Any pro tips? I’d love to hear from you!