The Kalem Book GitHub

This Book describes Kalem's main branch, which may be ahead of the latest release.

Elixir

The elixir plugin of getkalem/plugins makes Kalem an editor for Elixir, EEx and HEEx. It is a language plugin: a manifest, syntaxes and settings. Its own README lists the same and is kept with it.

1. What is followed

  • The grammar of the highlighter is the Sublime syntax of princemaple/elixir-sublime-syntax (MIT), with one addition (EEx's and HEEx's <%!-- --%> comment): Elixir with ~H sigils highlighted as HEEx, ~L as EEx, Markdown in @doc and @moduledoc, SQL in the strings of fragment(…) and sql(…); HEEx with components (<.button>, <Module.comp>), {…} attributes and <% … %>= blocks highlighted as Elixir. HEEx and EEx extend Sublime Text's HTML, which the plugin ships as a base only.
  • The server is the oracle for everything else: Expert, the Elixir team's language server, where it is installed; ElixirLS otherwise. Kalem shows what the server says and changes nothing in it.
Files Language
.ex, .exs, mix.lock, .formatter.exs, .credo.exs, .iex.exs, #! with elixir, iex or mix Elixir
.heex, .html.heex HEEx
.eex, .html.eex, .leex, .html.leex EEx

2. The project

The root is the outermost folder up from the file with a mix.exs, so an umbrella project is one workspace and its applications under apps/ are workspace folders. A file outside a Mix project gets no server (requireRoot), and the status bar says so. ElixirLS builds into .elixir_ls/ under the root with MIX_ENV test by default; set mixEnv in the plugin's settings to change it.

3. Installing a server

Server How
Expert A release from expert-lsp/expert (one file per platform, checksums beside it), renamed expert and put on the PATH
ElixirLS brew install elixir-ls, or a release unzipped to ~/.elixir-ls/release

kalem lsp status FILE says which is used and where it was found.

4. Known differences

Checked against Expert 0.1.11 and ElixirLS 0.27.2, on Elixir 1.20 with OTP 28, with the plugin's corpus project.

  • Expert starts by building its engine for the project's Elixir (about forty seconds the first time, cached after), then compiles and indexes the project; until the index is built it answers documentation, definitions and references about the project's own code with nothing (the standard library's at once). It reports this work in its log, not as progress; the plugin's busyLog turns those lines into progress in the status bar.
  • Expert names files by their real paths (/private/tmp for /tmp on macOS); Kalem sends servers the real path and maps places in their answers back to the path a file was opened under.
  • ElixirLS 0.27 on Elixir 1.20 answers the document symbols request with modules only, without their functions; Expert lists both.
  • Expert 0.1.11 has no signature help; ElixirLS has.
  • Dialyzer is off by default (its first run builds a large table and takes minutes); dialyzerEnabled in the plugin's settings turns it on.
  • A file outside a Mix project gets no server (requireRoot): it is highlighted, and the status bar says why.
  • Regular expressions in ~r are highlighted as strings: the package's PCRE syntax uses subroutine calls, which the pure-Rust regular expressions of Kalem's highlighter (fancy-regex) do not have.
  • CSS and JavaScript inside a HEEx <style> or <script> are highlighted with Kalem's built-in syntaxes, which are older than the HTML base the plugin ships.

5. Not implemented

No embedded iex: Kalem ships no REPL (D28), and a terminal is one key away. The test at the cursor (mix test FILE:LINE) runs with Test at Cursor, the project's tests with Test Project (SPC p T), their output in a document; the plugin gives mix test for both.