Permalink
Fetching contributors…
Cannot retrieve contributors at this time
3068 lines (2757 sloc) 104 KB

Table of Contents generated with DocToc

Elixir plugin

Build Status

This is a plugin that adds support for Elixir to JetBrains IntelliJ IDEA platform IDEs (0xDBE, AppCode, IntelliJ IDEA, PHPStorm, PyCharm, Rubymine, WebStorm).

It works with the free, open source Community edition of IntelliJ IDEA in addition to the paid JetBrains IDEs like Ultimate edition of IntelliJ. No feature is locked to a the paid version of the IDEs, but the plugin works best in IntelliJ because only IntelliJ supports projects with different languages than the default (Java for IntelliJ, Ruby for Rubymine, etc).

The plugin itself is free. Once you have your IDE of choice installed, you can install this plugin

Features

Project

NOTE: This feature only works in IntelliJ IDEA as it depends on an extension point unavailable in language-specific IDEs, like Rubymine.

New

If you want to create a basic (non-mix) Elixir project with a lib directory, perform the following steps.

  1. File > New > Project File > New > Project
  2. Select Elixir from the project type menu on the left
  3. Click Next File > New > Project > Elixir
  4. Select a Project SDK directory by clicking Configure. Project SDK
  5. Select a Project SDK directory by clicking Configure.
  6. The plugin will automatically find the newest version of Elixir installed. (NOTE: SDK detection only works for Linux, homebrew installs on OSX, and Windows. Open an issue with information about Elixir install locations on your operating system and package manager to have SDK detection added for it.)
  7. If the automatic detection doesn't find your Elixir SDK or you want to use an older version, manually select select the directory above the bin directory containing elixir, elixirc, iex, and mix.
  8. Click Next after you select SDK name from the Project SDK list.
  9. Change the Project name to the name your want for the project File > New > Project > Settings
  10. (Optionally) change the Project location if the directory does not match what you want
  11. (Optionally) expand More Settings to change the Module name, Content root, Module file location, and/or Project format. The defaults derived from the Project name and Project location should work for most projects.
  12. Click Finish
  13. Choose whether to open in a New Window or in This Window. File > New > Project > Window

From Existing Sources

Create project from existing sources

If you've already created a (non-mix) project, you can load it as an Elixir project into the plugin.

  1. File > New > Project From Existing Sources...
  2. Select the root directory of your project.
  3. Leave the default selection, "Create project from existing sources"
  4. Click Next
  5. Project name will be filled with the basename of the root directory. Customize it if you like.
  6. Project location will be the root directory.
  7. Click Next.
  8. If you previously opened the directory in IntelliJ or another JetBrains IDE, you'll be prompted to overwrite the .idea directory. Click Yes.
  9. You'll be prompted with a list of detected Elixir project roots to add to the project. Each root contains a mix.exs. Uncheck any project roots that you don't want added.
  10. Click Next.
  11. Select a Project SDK directory by clicking Configure.
  12. The plugin will automatically find the newest version of Elixir installed. (NOTE: SDK detection only works for Linux, homebrew installs on OSX, and Windows. Open an issue with information about Elixir install locations on your operating system and package manager to have SDK detection added for it.)
  13. If the automatic detection doesn't find your Elixir SDK or you want to use an older version, manually select select the directory above the bin directory containing elixir, elixirc, iex, and mix.
  14. Click Next after you select SDK name from the Project SDK list.
  15. Click Finish on the framework page. (No framework detection is implemented yet for Elixir.)
  16. Choose whether to open in a New Window or in This Window.
Import project from external model

If you've already created a mix project, you can load it as an Elixir project into the plugin.

  1. File > New > Project From Existing Sources...
  2. Select the root directory of your project.
  3. Select "Import project from external model"
  4. Select Mix File > New Project > From Existing Sources > Import project from external model > Mix
  5. Click Next
  6. The "Mix project root" will be filled in with the selected directory.
  7. (Optional) Uncheck "Fetch dependencies with mix" if you don't want to run mix deps.get when importing the project
  8. Ensure the correct "Mix Path" is detected. On Windows, the mix.bat, such as C:\Program Files (x86)\Elixir\bin\mix.bat should be used instead of the mix file without the extension.
  9. Ensure the "Mix Version" is as expected. The number in parentheses should match the Elixir version.
  10. Click Next
  11. All directories with mix.exs files will be selected as "Mix projects to import". To import just the main project and not its dependencies, click Unselect All.
  12. Check the box next to the project root to use only its mix.exs. (It will likely be the first checkbox at the top.)
  13. Click Next
  14. Select a Project SDK directory by clicking Configure.
  15. The plugin will automatically find the newest version of Elixir installed. (NOTE: SDK detection only works for Linux, homebrew installs on OSX, and Windows. Open an issue with information about Elixir install locations on your operating system and package manager to have SDK detection added for it.)
  16. If the automatic detection doesn't find your Elixir SDK or you want to use an older version, manually select select the directory above the bin directory containing elixir, elixirc, iex, and mix. (On Windows it is the directory containing elixir.bat, elixirc.bat, iex.bat, and mix.bat.)
  17. Click Finish after you select SDK name from the Project SDK list.

Project Structure

Project View

  • Excluded
    • _build (Output from mix)
    • rel (Output from exrm)
  • Sources
    • lib
  • Test Sources
    • test

Project Settings

Project Settings

The Project Settings include

  • Project Name
  • Project SDK

Module Settings

Sources

Module Settings > Sources

The Module Settings include Marking directories as

  • Excluded
  • Sources
  • Tests

Paths

Module Settings > Paths

Module paths list the output directories when compiling code in the module. There is a an "Output path" for dev MIX_ENV and "Test output path" for the test MIX_ENV.

Dependencies

Module Settings > Dependencies

Module dependencies are currently just the SDK and the sources for the module. Dependencies in deps are not automatically detected at this time.

New Elixir File

  1. Right-click a directory (such as lib or test in the standard mix new layout)
  2. Select New > Elixir File. New > Elixir File
  3. Enter an Alias for the Module name, such as MyModule or MyNamespace.MyModule.
  4. Select a Kind of Elixir File to use a different template. New > Elixir File > Kind

Empty module

An underscored file will be created in an underscored directory lib/my_namespace/my_module.ex) with the given module name with be created:

defmodule MyNamespace.MyModule do
  @moduledoc false

end

Elixir Application

An underscored file will be created in an underscored directory lib/my_namespace/my_module.ex) with the given module name with be created. It will have a start/2 function that calls MyNamespace.MyModule.Supervisor.start_link/0.

defmodule MyNamespace.MyModule do
  @moduledoc false

  use Application

  def start(_type, _args) do
    MyNamespace.MyModule.Supervisor.start_link()
  end
end

Elixir Supervisor

An underscored file will be created in an underscored directory lib/my_namespace/my_module.ex) with the given module name with be created. It will have a start_link/1 function that calls Supervisor.start_link/0 and init/1 that sets up the child specs. It assumes a MyWorker child that should be supervised :one_for_one.

defmodule MyNamespace.MyModule.Supervisor do
  @moduledoc false

  use Supervisor

  def start_link(arg) do
    Supervisor.start_link(__MODULE__, arg)
  end

  def init(arg) do
    children = [
      worker(MyWorker, [arg], restart: :temporary)
    ]

    supervise(children, strategy: :one_for_one)
  end
end

Elixir GenServer

An underscored file will be created in an underscored directory lib/my_namespace/my_module.ex) with the given module name with be created. It will have a start_link/2 function that calls GenServer.start_link/3 and the minimal callback implementations for init/1, handle_call/3, and handle_cast/2.

The Elixir use GenServer supplies these callbacks, so this template is for when you want to change the callbacks, but would like the stubs to get started without having to look them up in the documentation.

defmodule MyNamespace.MyModule do
  @moduledoc false

  use GenServer

  def start_link(state, opts) do
    GenServer.start_link(__MODULE__, state, opts)
  end

  def init(_opts) do
    {:ok, %{}}
  end

  def handle_call(_msg, _from, state) do
    {:reply, :ok, state}
  end

  def handle_cast(_msg, state) do
    {:noreply, state}
  end
end

Elixir GenEvent

An underscored file will be created in an underscored directory lib/my_namespace/my_module.ex) with the given module name with be created. The minimal callback implementations for init/1, handle_event/2, and handle_call/2, handle_info/2.

The Elixir use GenEvent supplies these callbacks, so this template is for when you want to change the callbacks, but would like the stubs to get started without having to look them up in the documentation.

defmodule MyNamespace.MyModule do
  @moduledoc false

  use GenEvent

  # Callbacks

  def init(_opts) do
    {:ok, %{}}
  end

  def handle_event(_msg, state) do
    {:ok, state}
  end

  def handle_call(_msg, state) do
    {:ok, :ok, state}
  end

  def handle_info(_msg, state) do
    {:ok, state}
  end
end

Syntax Highlighting and Semantic Annotation

Syntax highlighting of lexer tokens and semantic annotating of parser elements can be customized in in the Color Settings page for Elixir (Preferences > Editor > Color & Fonts > Elixir).

Text Attribute Key Display Name Tokens/Elements Scheme
Default Darcula
Alias String
Atom
  • :one
  • <<>>:
Braces and Operators Bit
  • <<
  • >>
Braces and Operators Braces
  • {
  • }
Braces and Operators Brackets
  • [
  • ]
Braces and Operators Character Token ?
Braces and Operators Comma ,
Braces and Operators Dot .
Braces and Operators Interpolation
  • #{
  • }
Braces and Operators Maps and Structs Maps
  • %{
  • }
Braces and Operators Maps and Structs Maps
  • %
  • {
  • }
Braces and Operators Operation Sign
  • =
  • +
  • *
  • ==
  • !
  • &&
  • ||
  • |>
  • ^
Braces and Operators Parentheses
  • (
  • )
Braces and Operators Semicolon ;
Calls Function inspect *Only the Italic attribute *Only the Italic attribute
Calls Macro inspect *Only the Bold and Italic attributes *Only the Bold and Italic attributes
Calls Predefined
  • Kernel
    • functions
    • macros
  • Kernel.SpecialForms
    • macros
*Only the Foreground attribute *Only the Foreground attribute
Comment # Numbers
Keywords end
Module Attributes @custom_attr
Module Attributes Documentation @doc
Module Attributes Documentation Text Simple module docstring
Module Attributes Types Callback func
Module Attributes Types Specification func
Module Attributes Types Type parameterized
Module Attributes Types Type Parameter type_parameter
Numbers Base Prefix Non-Decimal
  • 0b
  • 0x
  • 0o
Numbers Base Prefix Obsolete Non-Decimal
  • 0B
  • 0X
Numbers Decimal Exponent, Mark, and Separator
  • e
  • .
  • _
Numbers Digits Invalid
  • 2
  • o
  • r
  • 888
Numbers Digits Valid
  • 1234
  • 1A
  • beef
  • 123
Textual Character List 'This is a list'
Textual Escape Sequence \x{12}
Textual Sigil
  • ~r//
  • ~R''
  • ~w()
  • ~W()
Textual String "Hello world"
Variables Ignored _
Variables Parameter
  • a
  • b
Variables Variable pid

Grammar parsing

Built on top of highlighted tokens above, the parser understands the following parts of Elixir grammar as valid or allows the grammar because they contain correctable errors:

  • Empty Parentheses (())
  • Keyword Lists
    • Keyword Keys - Aliases, identifiers, quotes, or operators when followed immediately by a colon and horizontal or vertical space.
    • Keyword Values - Empty parentheses (()) and matched expressions.
  • Matched Expressions, in other words, unary and binary operations on variable, function, and macro names and values (numbers, strings, char lists, sigils, heredocs, true, false, and nil).
  • No Parentheses expressions, which are function calls with neither parentheses nor do blocks that have either (1) a positional argument and keyword arguments OR (2) two or more positional arguments with optional keyword arguments.
  • Anonymous function calls .() with either no arguments; a no parentheses arguments expression as an argument; keywords as an argument; positional argument(s); or positional arguments followed by keywords as arguments.
  • Remote function calls (Alias.function, :atom.function, etc) and local function calls (function) with...
    • No Parentheses with...
      • No Arguments (Alias.function)
      • Keywords (Alias.function key: value)
      • Nested No Parentheses Call (Alias.function Inner.function positional, key: value)
      • Positional and Keyword arguments (Alias.function positional, key: value)
      • Matched Expression (Alias.function 1 + 2)
    • Parentheses with...
      • No arguments (Alias.function())
      • No Parentheses Call (Alias.function(Inner.function positional, key: value)
      • Keywords (Alias.function(key: value))
      • Positional and Keyword arguments (Alias.function(positional, key: value))
      • Trailing parentheses for quoting (def unquote(variable)(positional))
  • Bracket expression (variable[key])
  • Block expressions (function do end)
  • Unmatched expressions, in other words combinations of block expressions and matched expressions.

Inspections

Inspections mark sections of code with warnings and errors. They can be customized from the Preferences > Inspections > Elixir.

Elixir Inspections

Ambiguous nested calls

Detects when compiler will throw unexpected comma. Parentheses are required to solve ambiguity in nested calls. Function calls with multiple arguments without parentheses cannot take as arguments functions with multiple arguments without parentheses because which functional gets which arguments is unclear as in the following example:

outer_function first_outer_argument,
               # second argument is another function call without parentheses, but with multiple arguments
               inner_function first_inner_argument,
               ambiguous_keyword_key: ambiguous_keyword_value

To fix the ambiguity if first_inner_keyword_key: first_inner_keyword_value should be associated, add parentheses around the inner function's arguments:

# keywords are for inner function
outer_function first_outer_argument
               inner_function(
                 first_inner_argument
                 ambiguous_keyword_key: ambiguous_keyword_value
               )

# keywords are for outer function
outer_function first_outer_argument
               inner_function(
                 first_inner_argument
               ),
               ambiguous_keyword_key: ambiguous_keyword_value

Ambiguous nested calls preferences


Preferences > Inspections > Elixir > Ambiguous nested calls

Ambiguous nested calls error


Ambiguous nested call inspection marks the error on the comma that causes the ambiguity.

Ambiguous nested calls inspection


Mousing over the comma marked as an error in red (or over the red square in the right gutter) will show the inspection describing the error.

Ambiguous parentheses

Detects when compiler will throw unexpected parenthesis. If you are making a function call, do not insert spaces in between the function name and the opening parentheses. Function calls with space between the function name and the parentheses cannot distinguish between function calls with parentheses, but with an accidental space before the ( and function calls without parentheses where the first positional argument is in parentheses.

Empty Parentheses
function ()

To fix the ambiguity remove the space or add outer parentheses without the space if the first argument should be ():

# extra space, no arguments to function
function()

# first argument is `()`
function(())
Keywords in Parentheses
function (key: value)

Keywords inside parentheses is not valid, so the only way to fix this is to remove the space

function(key: value)
Positional arguments in Parentheses
function (first_positional, second_positional)

A list of positional arguments in parenthenses is not valid, so the only way to fix this is to remove the space

function(first_positional, second_positional)

Ambiguous parentheses preferences


Preferences > Inspections > Elixir > Ambiguous parentheses

Ambiguous parentheses error


Ambiguous parentheses inspection marks the error on the parenthetical group surrounded by the parentheses that are ambiguous due to the preceding space.

Ambiguous parentheses


Mousing over the parenthetical group marked as an error in red (or over the red square in the right gutter) will show the inspection describing the error.

Keyword pair colon (:) used in type spec instead of type operator (::)

Type specifications separate the name from the definition using ::.

@type name: definition

Replace the : with ::

@type name :: definition

Keywords appear before the end of list.

one.(
  one,
  two positional, key: value,
  three
)

Keywords can only appear at the end of an argument list, so either surround the no parentheses expression argument with parentheses, or move the the keywords to the end of the list if it wasn't meant to be a no parentheses expression.

one.(
  one
  two(positional, key: value),
  three
)

OR

one.(
  one,
  two,
  three,
  key: value
)

Keywords Not At End


Preferences > Inspections > Elixir > Keywords Not At End

Keywords Not At End error


Keywords Not At End inspection marks the error over the keywords that need to be surrounded by parentheses or moved to the end of the list.

Keywords Not At End inspection


Mousing over the keywords marked as an error in red (or over the red square in the right gutter) will show the inspection describing the error.

Match operator (=) used in type spec instead of type operator (::)

Type specifications separate the name from the definition using ::.

@type name = definition

Replace the = with ::

@type name :: definition

Quick Fixes

Quick Fixes are actions IntelliJ can take to change your code to correct errors (accessed with Alt+Enter by default).

Convert : to :: in type specs

If a type specification uses a single : instead of ::, then hit Alt+Enter on the : to change it to :: and fix the type spec.

Convert = to :: in type specs

If a type specification uses = instead of ::, then hit Alt+Enter on the = to change it to :: and fix the type spec.

Remove space in front of ambiguous parentheses

If a set of parentheses is marked as ambiguous then the space before it can be removed to disambiguate the parentheses with Alt+Enter. (Will vary based on keymap.)

Remove spaces before ambiguous parentheses


Hitting Alt+Enter on ambiguous parentheses error will bring up the Local Quick Fix, "Remove spaces between function name and parentheses". Hit Enter to accept and remove the space.

Code Folding

You can collaspe (fold) pre-defined regions of your Elixir code to make it easier to quickly scroll through files or hide details you don't care about right now.

Controls

Collapsing
  1. Position cursor between lines with with downward facing - arrow and upward facing - arrow.
  2. Cmd+-
Expanding
  1. Position cursor on the collapsed line with the square +
  2. Cmd++

Regions

Expanded Collapsed Folded By Default?
do end do: ... No
-> and right operand -> ... No
@doc VALUE @doc "..." No
@moduledoc VALUE @moduledoc "..." No
@typedoc VALUE @typedoc "..." No
alias ALIAS1
alias ALIAS1
alias ... Yes
import ALIAS1
import ALIAS2
import ... Yes
require ALIAS1
require ALIAS2
require ... Yes
use ALIAS1
use ALIAS2
use ALIAS1 Yes
@for FOR in defimpl PROTOCOL, for: FOR Yes
@protocol PROTOCOL in defimpl PROTOCOL, for: FOR Yes
@MODULE_ATTRIBUTE VALUE in @MODULE_ATTRIBUTE VALUE Yes

Commenter

You can comment or uncomment the current line or selected block of source. By selecting a block of source first you can quickly comment out and entire function if you're trying to track down a compiling or testing error that's not giving a helpful line number.

Using the menus

  1. Highlight one or more lines
  2. Comment (or Uncomment) with one of the following: a. Code > Comment with Line Comment b. On OSX the key binding is normally Cmd+/.

Delimiters

Auto-inserting

The right-delimiter will be automatically inserted when the left delimiter is typed. In some cases, to prevent false positives, the the delimiter is only completed if when used for sigils.

Preceded By Left Right
do end
fn end
[ ]
{ }
( )
' '
''' '''
" "
""" """
<< >>
~<sigil-name> < >
~<sigil-name> / /
~<sigil-name> | |

Matching

All delimiters that are auto-inserted are also matched for highlighting

Left Right
do end
fn end
[ ]
{ }
( )
' '
''' '''
" "
""" """
<< >>
< >
/ /
| |

Building/Compiling

Settings

Build, Execution, Deployment > Compiler > Elixir Compiler

  • Compile project with mix (use mix compile instead of elixirc directly)
  • Attach docs (don't use --no-docs elixirc flag)
  • Attach debug info (don't use --no-debug-info elixirc flag)
  • Ignore module conflict (use --ignore-module-conflict elixirc flag)

Individual File

  1. Have a file selected in Project view with the Project view in focus OR have an Editor tab in focus
  2. Build > Compile 'FILE_NAME'
  3. Build results will be shown
    • If compilation is successful, you'll see "Compilation completed successfully" in the Event Log
    • If compilation had errors, you'll see "Compilation completed with N errors and M warnings" in the Event Log and the Messages Compile tab will open showing a list of Errors Messages Compile

Project

  1. Build > Make Project
  2. Build results will be shown
    • If compilation is successful, you'll see "Compilation completed successfully" in the Event Log
    • If compilation had errors, you'll see "Compilation completed with N errors and M warnings" in the Event Log and the Messages Compile tab will open showing a list of Errors Messages Compile

Live Templates

Live Templates are snippets of code that can be inserted quickly and have placeholder locations that the cursor will automatically jump to when using the template. Whenever you start typing, Live Templates will start matching against the shortcuts. A template can be selected with Tab.

Live Templates can be customized in Preferences > Editor > Live Templates > Elixir.

Metasyntactic variables are locations where the cursor will jump to. END is the final location of the cursor.
Shortcut Code
@doc

@doc """
ONE
"""
END
case

case ONE do
  TWO -> END
end
cond

cond do
  END
end
def

def NAME do
  END
end        
def,

def NAME, do: END        
defi

defimpl PROTOCOL, for: TYPE do
  END
end  
defm

defmodule ALIAS do
  END
end
defmac

defmacro MACRO_NAME do
  END
end
defmacp

defmacrop MACRO_NAME do
  END
end
defover

defoverridable [NAME: END]
defp

defp NAME do
  END
end
defpro

defprotocol PROTOCOL do
  END
end
defs

defstruct [END]
do
 
do
  END
end
doc

@doc """
ONE
"""
END
fn

fn ARGS -> END end
for

for A <- B do
  END
end
if

if TRUE do
  END
end
ife

if TRUE do
  OK
else
  END
end
ii

IO.inspect(END)
mdoc

@moduledoc """
ONE
"""
END
rec

receive do
  ONE -> END
end
test

test "TESTDESC" do
  END
end
try

try do
  ONE 
rescue
  TWO -> END

Run Configurations

Mix Tasks

Much like rake tasks in Rubymine, this plugin can run mix tasks.

  1. Run > Edit Configurations... Edit Run Configurations
  2. Click +
  3. Select "Elixir Mix" Add New Elixir Mix
  4. Fill in the "Program arguments" starting with the name of the mix task followed by any arguments to that task
  5. Fill in the "Working directory"
    • Type the absolute path to the directory.
    • Select the path using directory picker by clicking the ... button
  6. (Optionally) click the ... button on the "Environment variables" line to add environment variables.
  7. Click "OK" to save the Run Configuration and close the dialog
  8. Click the Run arrow in the Toolbar to run the mix task Run
  9. The Run pane will open, showing the results of the mix task.
    • If there is an error with a FILE:LINE stack frame, it will be a clickable link that will take you to that location Error link

mix test

The mix test task gets a special type of Run Configuration, Elixir Mix ExUnit. Using this Run Configuration type instead, of the basic Elixir Mix Run Configuration will cause the IDE to attach a special formatter to mix test, so that you get the standard graphical tree of Test Results

Creating mix test Run Configurations Manually
  1. Run > Edit Configurations... Edit Run Configurations
  2. Click +
  3. Select "Elixir Mix ExUnit" Add New Elixir Mix ExUnit
  4. Fill in the "Program arguments" with the argument(s) to pass to mix test. Normally, this will be a directory like test, relative to the "Working directory"
  5. Fill in the "Working directory"
    • Type the absolute path to the directory.
    • Select the path using directory picker by clicking the ... button
  6. (Optionally) click the ... button on the "Environment variables" line to add environment variables.
  7. Click "OK" to save the Run Configuration and close the dialog
  8. Click the RUn arrow in the Toolbar to run the mix test task
  9. The Run pane will open showing the Test Results Test Results

While you can create Elixir Mix ExUnit run configurations manually using the Run > Edit Configurations... menu, it is probably more convenient to use the context menu.

Creating mix test Run Configurations from context

The context menu must know that the the directory, file, or line you are right-clicking is a test. It does this by checking if the current directory or an ancestor is marked as a Test Sources Root.

  1. In the Project pane, ensure your OTP application's test directory is marked as a Test Sources Root
    1. Check if the test directory is green. If it is, it is likely a Test Sources Root. This color may differ in different themes, so to be sure you can check the context menu
    2. Right-click the test directory.
    3. Hover over "Mark Directory As >"
      • If "Unmark as Test Sources Root" is shown, then the directory is already configured correctly, and create from context will work. Mark Directory As &gt; Unmark as Test Sources Root
      • If "Test Sources Root" is shown, then the directory need to be configured by clicking that entry Mark Directory As &gt; Test Sources Root
Creating/Running mix test Run Configurations from directory
  1. Right-click the directory in the Project pane
  2. Click "Run Mix ExUnit", which will both create the Run Configuration and Run it. Run Mix ExUnit
    • If you want to only create the Run Configuration, select "Create Mix ExUnit" instead

Alternatively, you can use keyboard shortcuts

  1. Select the directory in the Project pane.
  2. Ctrl+Shift+R will create the Run Configuration and Run it.
Creating/Running mix test Run Configurations from file
  1. Right-click the file in the Project pane
  2. Click "Run Mix ExUnit", which will both create the Run Configuration and Run it.
    • If you want to only create the Run Configuration, select "Create Mix ExUnit" instead

Alternatively, you can use keyboard shortcuts

  1. Select the directory in the Project pane.
  2. Ctrl+Shift+R will create the Run Configuration and Run it.

Finally, you can use the editor tabs

  1. Right-click the editor tab for the test file you want to run Run Mix ExUnit
  2. Click "Run Mix ExUnit", which will both create the Run Configuration and Run it.
    • If you want to only create the Run Configuration, select "Create Mix ExUnit" instead
Creating/Running mix test Run Configurations from line

If you want to be able to run a single test, you can create a Run Configuration for a line in that test

  1. Right-click a line in the test file Run Mix ExUnit
  2. Click "Run Mix ExUnit", which will both create the Run Configuration and Run it.
    • If you want to only create the Run Configuration, select "Create Mix ExUnit" instead

Alternatively, you can use keyboard shortcuts

  1. Place the cursor on the line you want to test
  2. Ctrl+Shift+R will create the Run Configuration and Run it.

Completion

Aliases and Modules

When you start typing an Alias, completion will look in three locations:

  1. alias aliased names in the current file
    1. Suffix for alias Prefix.Suffix
    2. MultipleAliasA or MultipleAliasB for alias Prefix.{MultipleAliasA, MultipleAliasB}
    3. As for alias Prefix.Suffix, as: As
  2. Indexed module names (as available from Go To Symbol)
    1. Prefix.Suffix from defmodule Prefix.Suffix
    2. MyProtocol from defprotocol MyProtocol
    3. MyProtocol.MyStruct
      1. defimpl MyProtocol, for: MyStruct
      2. defimpl MyProtocol nested under defmodule MyStruct
  3. Nested modules under aliased names
    1. Suffix.Nested for alias Prefix.Suffix where Prefix.Suffix.Nested is an indexed module, implementation or protocol name.
    2. MultipleAliasA.Nested for alias Prefix.{MultipleAliasA, MultipleAliasB} where Prefix.MultipleAliasA.Nested alias Prefix.{MultipleAliasA, MultipleAliasB} is an indexed module, implementation or protocol name.
    3. As.Nested for alias Prefix.Suffix, as: As where Prefix.Suffix.Nested is an indexed module, implementation, or protocol name.
Aliases inside { }

When you start typing inside { } for alias Prefix.{} or import Prefix.{}, completion will look for nested modules under Prefix and then remove the Prefix., so completion will look like Suffix.

Function and Macro Calls

Completion uses the same presentation as Structure, so you can tell whether the name is function/macro (Time), whether it is public/private (Visibility) and the Module where it is defined. Between the icons and the Modules is the name itself, which is highlighted in bold, the parameters for the call definition follow, so that you can preview the patterns required for the different clauses.

Function and Macro Calls Completion

Qualified

Qualified functions and macro calls will complete using those functions and macros defined in the qualifying Module (defmodule), Implementation (defimpl) or Protocol (defprotocol). Completion starts as shown as . is typed after a qualifying Alias.

Unqualified

Function and macro calls that are unqualified are completed from the index of all function and macro definitions, both public and private. (The index contains only those Elixir functions and macro defined in parsable source, such as those in the project or its dependencies. Erlang functions and Elixir functions only in compiled .beam files, such as the standard library will not complete.) Private function and macros are shown, so you can choose them and then make the chosen function or macro public if it is a remote call.

Module Attributes

Module attributes declared earlier in the file can be completed whenever you type @ and some letter. If you want to see all module attributes, you can type @a, wait for the completions to appear, then delete the @ to remove the filtering to a.

Parameters and Variables

Parameter and variable usages can be completed whenever typing an identifier. The completions will include all variables know up from that part of the file. It can include variables from outside macros, like quote blocks.

Go To Declaration

Go To Declaration is a feature of JetBrains IDEs that allows you to jump from the usage of a symbol, such as a Module Alias, to its declaration, such as the defmodule call.

Alias

  1. Place the cursor over an Alias with an aliased name setup by alias
    1. Suffix if alias Prefix.Suffix called
    2. MultipleAliasA if alias Prefix.{MultipleAliasA, MultipleAliasB} called
    3. As if alias Prefix.Suffix, as: As
  2. Activate the Go To Declaration action with one of the following:
    1. Cmd+B
    2. Select Navigate > Declaration from the menu.
    3. Cmd+Click
  3. A Go To Declaration lookup menu will appear, allowing you to jump either the alias that setup the aliased name or jumping directly to defmodule of the unaliased name. Select which declaration you want
    1. Use arrow keys to select and hit Enter
    2. Click

Function or Macro

You'll know if function or macro usage is resolved and Go To Declaration will work if the call is annotated, which in the default themes will show up as italics.

Imported Functions or Macros
  1. Place the cursor over name of the function or macro call.
  2. Activate the Go to Declaration action with one of the following:
    1. Cmd+B
    2. Select Navigate > Declaration from the menu.
    3. Cmd+Click
  3. A Go To Declaration lookup menu will appear, allowing you to jump to either the import that imported the function or macro or jumping directly to the function or macro definition clause. Select which declaration you want.
    1. Use arrow keys to select and hit Enter
    2. Click
Local Functions or Macros
  1. Place the cursor over name of the function or macro call.
  2. Activate the Go to Declaration action with one of the following:
    1. Cmd+B
    2. Select Navigate > Declaration from the menu.
    3. Cmd+Click
  3. Whether a lookup a Go To Declaration lookup menu appears depends on the number of clauses in the function or macro definition:
    1. If there is only one clause in the function or macro definition, you'll jump immediately to that clause
    2. If there is more than one clause in the function or macro definition, a Go To Declaration lookup menu will appear, allowing you to jump to either the import that imported the function or macro or jumping directly to the function or macro definition clause. Select which declaration you want.
      1. Use arrow keys to select and hit Enter
      2. Click
Remote Functions or Macros
  1. Place the cursor over name of the function or macro call that is qualified by an Alias.
  2. Activate the Go to Declaration action with one of the following:
    1. Cmd+B
    2. Select Navigate > Declaration from the menu.
    3. Cmd+Click
    1. If there is only one clause in the function or macro definition, you'll jump immediately to that clause
    2. If there is more than one clause in the function or macro definition, a Go To Declaration lookup menu will appear, allowing you to jump to either the import that imported the function or macro or jumping directly to the function or macro definition clause. Select which declaration you want.
      1. Use arrow keys to select and hit Enter
      2. Click

Module

  1. Place the cursor over a fully-qualified Alias
    1. A.B in A.B.func()
    2. A.B in alias A.B
    3. B in alias A.{B, C}
  2. Activate the Go To Declaration action with one of the following:
    1. Cmd+B
    2. Select Navigate > Declaration from the menu.
    3. Cmd+Click

If you hold Cmd and hover over the Alias before clicking, the target declaration will be shown.

Go To Declaration Demonstration

Module Attribute

  1. Place the cursor over a @module_attribute
  2. Activate the Go To Declaration action with one of the following:
    1. Cmd+B
    2. Select Navigate > Declaration from the menu.
    3. Cmd+Click

If you hold Cmd and hover over the @module_attribute before clicking, the target declaration will be shown.

Parameters and Variables

  1. Place the cursor over a parameter or variable usage
  2. Active the Go To Declaration action with one of the following:
    1. Cmd+B
    2. Select Navigate > Declaration from the menu.
    3. Cmd+Click

If you hold Cmd and hover over the variable before clicking, it will say parameter or variable, which matches the annotation color.

Go To Symbol

Go To Symbol is a way to search for any of the following by name:

  • Call definition clauses (def, defp, defmacro, and defmacrop)
  • Callbacks (@callback and @macrocallback)
  • Call definition specifications (@spec)
  • Call definition heads (foo(bar)) for delegation (defdelegate foo(bar), to: BAZ)
  • Implementations (defimpl)
  • Protocols (defprotocol)

You can bring up Go To Symbol with the keyboard shortcut (⌥⌘O on OSX) or using the menus (Navigate > Symbol...).

Go To Test

Go to Test allows you to jump from the a Source Module to its corresponding Test Module

  1. Have the cursor in the body of a Module
  2. Active the Go To Test action with one of the following:
    1. Shift+Cmd+T
    2. Select Navigate &gt Test from the menu.

Go To Test Subject

Go to Test Subject allows you to jump from the a Test Module to its corresponding Source Module

  1. Have the cursor in the body of a Test Module
  2. Active the Go To Test Subject action with one of the following:
    1. Shift+Cmd+T
    2. Select Navigate &gt Test Subject from the menu.

Find Usage

Find Usage is a feature of JetBrains IDEs that allows you to find all the places a declared symbol, such a Module Alias in a defmodule, is used, including in strings and comments.

Module

  1. Place cursor over an defmodule Alias.
  2. Activate the Find Usage action with one of the following: a. i. Right-click the Alias ii. Select "Find Usages" from the context menu b. Select Edit > Find > Find Usages from the menu c. Alt+F7

Find Module Usage Demonstration

Module Attribute

  1. Place cursor over the @module_attribute part of the declaration @module_attribute value.
  2. Activate the Find Usage action with one of the following: 1. 1. Right-click the module attribute 2. Select "Find Usages" from the context menu
    1. Select Edit > Find > Find Usages from the menu
    2. Alt+F7

Parameters and Variables

  1. Place cursor over the parameter or variable declaration.
  2. Active the Find Usage action with one of the following: 1. 1. Right-click the Alias 2. Select "Find Usages" from the context menu
    1. Select Edit > Find > Find Usages from the menu
    2. Alt+F7

Refactor

Rename

Module Attribute
  1. Place the cursor over the @module_attribute usage or declaration.
  2. Active the Rename Refactoring action with one of the following: 1. 1. Right-click the module attribute 2. Select Refactoring from the context menu 3. Select "Rename..." from the Refactoring submenu
    1. Shift+F6
  3. Edit the name inline and have the declaration and usages update.
Parameters and Variables
  1. Place the cursor over the parameter or variable usage or declaration
  2. Active the Rename Refactoring action with one of the following: 1. 1. Right-click the module attribute 2. Select Refactoring from the context menu 3. Select "Rename..." from the Refactoring submenu
    1. Shift+F6
  3. Edit the name inline and have the declaration and usages update.

Structure

You can view the structure of the currently open editor tab using the Structure tool window.

Viewing Structure

  • View > Tool Windows > Structure
  • Click the Structure Button (normally in the left tool buttons)
    1. If you can't see the Tool Buttons, they can be enabled with View > Tool Buttons
  • Cmd+7

Buttons

Structure Buttons

The buttons in the Structure tool are broken into 4 categories:

Sorters

Structure Sorter Buttons

Icon Tooltip Description
Sort by Time Sort by Time When the defined callable is usable:
  1. Compile time
  2. Both or None
  3. Runtime
Macros are compile time while functions are runtime.
Sort by Visibility Sort by Visibility Whether the element visible outside its defining module:
  1. Public
  2. Private
Sort Alphabetically Sort Alphabetically Sort by name

NOTE: When any combination of sorters is turned on, they are sorted from left to right (as shown in the button bar), so with all 3 sorters on, the elements are first grouped by Time, then inside each Time group, they are sorted by Visibility, then in each Visibility group, they are sorted by name.

Providers

Structure Provider Buttons

The providers add nodes not in the text of the file, but that will appear in the compiled Module.

Icon Tooltip Description
Show Used Show Used In Modules that `use ` or `use , arg`, the elements from the last `quote` block in the `__using__/1` for `` are injected.
Expanders

Structure Expander Buttons

The expanders expand or collapse all the elements in the Structure tool window.

Icon Tooltip Description
Expand All Expand All Expand All Elements in the Structure tool window
Expand All Collapse All Collapse All Elements in the Structure tool window
Autoscrollers

Structure Autoscroller Buttons

The autoscrollers link together the editor tab's location and the Structure tool windows selected element.

Icon Tooltip Description
Autoscroll to Source Autoscroll to Source Clicking an element in the Structure tool window will scroll the editor window to the location of the corresponding source.
Autoscroll from Source Autoscroll from Source When moving the cursor in the editor window, the selected element in the Structure tool window will change to the corresponding element.

Elements

Icons
Time

The Time icons indicate whether the element is usable at compile time or runtime.

Icon Tooltip Description
Compile Time Compile Time The element is used or checked at compile time and (may) not even be accessible at run time, such as macros.
Runtime Runtime The element is usable at runtime, such as a function.
Visibility

The Visibility icons indicated whether the element is usable outside its defining Module.

Icon Tooltip Description
Public Public Public elements are accessible outside their defining Module.
Private Private Private elements are only accessible in their defining Module. The macros that define private elements usually end in p.
Call to Element
Call Icons Text Description
Macro Type Time Visibility Function Module Local Overridable Override
def Runtime Public Function NAME/ARITY Groups together def with the same name and arity.
Runtime Public Function Module Local NAME[(][ARGUMENTS][)][when ...] The function head for function clause, including the name, arguments, and when if present
defdelegate Runtime Module Local defdelegate append_first: false|true, to: ALIAS|ATOM Groups together all the delegated functions for a single defdelegate call.
defdelegate func(arg), to: ALIAS Runtime Public Function NAME/ARITY Groups together implied def and any explicit @spec for the given function head (func(arg))
defdelegate func(arg), to: ALIAS Runtime Public Function Module Local func(arg) The function head implied by the defdelegate list of function heads.
defexception Exception RELATIVE_ALIAS The exception has the same name as the parent Module, but will display with only the relative name (the last Alias without a .) with its location as the qualifying Alias.
defexception Struct %RELATIVE_ALIAS{} Exceptions are defined as structs, so any defexception also defines a struct with the same name.
defexception list_or_keywords Field NAME: DEFAULT_VALUE The fields and default values (or nil if a list is used instead of a keyword list) for the struct as passed in the first argument to defexception.
defimpl PROTOCOL, for: MODULE Protocol Override MODULE (PROTOCOL) defimpl defines a protocol implementation that defines a Module that concatenates the PROTOCOL name and the MODULE name. If no :for is given, then the outer Module is used.
defmacro Compile Time Public Function NAME/ARITY Groups together defmacro with the same name and arity.
Compile Time Public Function Module Local NAME[(][ARGUMENTS][)][when ...] The macro head for macro clause, including the name, arguments, and when if present
defmacrop Compile Time Private Function NAME/ARITY Groups together defmacrop with the same name and arity.
Compile Time Private Function Module Local NAME[(][ARGUMENTS][)][when ...] The macro head for macro clause, including the name, arguments, and when if present
defmacro AND defmacrop Compile Time Unknown Function NAME/ARITY Groups together defmacro AND defmacrop with the same name and arity. This will be a compile error, but is represented with Unknown Unknown for the Visibility until corrected.
defmodule ALIAS Module RELATIVE_ALIAS (QUALIFIER) Top-level Modules show only the ALIAS with no location, while qualified Aliases or nested Modules show the RELATIVE_ALIAS and the QUALIFIER as the location.
defoverridable Overridable Mark previously declared functions as overridable. Overridable functions are listed as children of this element.
defoverridable NAME: ARITY, ... Runtime Public Function Overridable NAME/ARITY The NAME and ARITY of the function that is overridable. Matches the icon and text for def, but with the addition of Overridable Overridable
defp Runtime Private Function NAME/ARITY Groups together def with the same name and arity.
Runtime Private Function Module Local NAME[(][ARGUMENTS][)][when ...] The function head for function clause, including the name, arguments, and when if present
def AND defp Runtime Unknown Function NAME/ARITY Groups together def AND defp with the same name and arity. This will be a compile error, but is represented with Unknown Unknown for the Visibility until corrected.
defprotocol PROTOCOL Protocol Overridable PROTOCOL The protocol name. Functions required by the protocol are children of this element.
defstruct Struct %RELATIVE_ALIAS{} Structs have the same RELATIVE_ALIAS as their parent Module.
defstruct NAME: DEFAULT_VALUE, ... Field NAME: DEFAULT_VALUE The fields and default values (or nil if a list is used instead of a keyword list) for the struct.

Installation

Inside IDE using JetBrains repository

  1. Preferences
  2. Plugins
  3. Browse Repositories
  4. Select Elixir
  5. Install plugin
  6. Apply
  7. Restart the IDE

Inside IDE using Github releases

In browser

  1. Go to releases.
  2. Download the lastest zip.

In IDE

  1. Preferences
  2. Plugins
  3. Install plugin from disk...
  4. Select the downloaded zip.
  5. Apply
  6. Restart the IDE.

Screenshots

Color Settings New Elixir File

Error reporting

If the plugin encounters an error, there is a custom error handler registered, so you can open a pre-populated issue in your browser.

  1. Click the red error notification in bottom right corner of the IDE window. Fatal IDE Errors
  2. Fill in a description of what you were doing when the error occurred.
  3. Click "Open Issue against https://github.com/KronicDeth/intellij-elixir"
  4. The IDE will open your browser to https://github.com/KronicDeth/intellij-elixir/issues/new Write New Issue
  5. The title will be filled as [auto-generated], but if you can summarize the issue, change the title.
  6. If the "Fatal IDE Errors" dialog has Attachments, copy their contents to the Attachments section of the issue body.
  7. Review for IP disclosures. This will be public, so use your best judgement of how much of your code to post in the issue.
  8. Click the "Preview" tab to ensure the Markdown formatting looks correct.
  9. Click "Submit new issue".

Donations

If you would like to make a donation you can use Paypal:

Donate

If you'd like to use a different donation mechanism (such as Patreon), please open an issue.

Public Donors

I'd like to thank those who have donated to help support this project.