diff --git a/README.md b/README.md index b323c69..956f58c 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,28 @@ [![License GPL 3][badge-license]](http://www.gnu.org/licenses/gpl-3.0.txt) [![Build Status](https://github.com/elixir-editors/emacs-elixir/actions/workflows/ci.yml/badge.svg)](https://github.com/elixir-editors/emacs-elixir/actions) +[![NonGNU ELPA](https://elpa.nongnu.org/nongnu/elixir-mode.svg)](https://elpa.nongnu.org/nongnu/elixir-mode.html) [![MELPA Stable](http://stable.melpa.org/packages/elixir-mode-badge.svg)](http://stable.melpa.org/#/elixir-mode) [![MELPA](http://melpa.org/packages/elixir-mode-badge.svg)](http://melpa.org/#/elixir-mode) +> **WARNING** +> There is a built-in Elixir mode with tree-sitter support from Emacs 30+ that can also be used with Emacs 29 +> This repository is for an older elixir-mode built with SMIE (Simple Minded Indentation Engine) which is not +> as advanced as tree-sitter for a language like Elixir. + # Elixir Mode Provides font-locking, indentation and navigation support for the [Elixir programming language.](http://elixir-lang.org/) -- [Installation](#installation) - - [Via package.el](#via-packageel) - - [Via el-get](#via-el-get) - - [Manual](#manual) -- [Usage](#usage) - - [Interactive Commands](#interactive-commands) - - [Configuration](#configuration) - - [Keymapping](#keymapping) -- [Notes](#notes) -- [Elixir Tooling Integration](#elixir-tooling-integration) -- [Elixir Format](#elixir-format) -- [Treesitter Support](#treesitter-support) -- [History](#history) -- [Contributing](#contributing) -- [License](#license) - ## Installation +`elixir-mode` is available on [NON-GNU ELPA](https://elpa.nongnu.org/), +[MELPA STABLE](https://stable.melpa.org/) and [MELPA](https://melpa.org/). + ### Via package.el `package.el` is the built-in package manager in Emacs. -`elixir-mode` is available on the two major community maintained repositories - -[MELPA STABLE](https://stable.melpa.org/) and [MELPA](https://melpa.org/). - You can install `elixir-mode` with the following command: M-x package-install [RET] elixir-mode [RET] @@ -52,20 +42,20 @@ If the installation doesn't work try refreshing the package list: 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 `Elixir-Mode`, as the `master` branch is normally quite stable and -"stable" (tagged) builds are released somewhat infrequently. +obtaining `Elixir-Mode`. -With the most recent builds of Emacs, you can pin `Elixir-Mode` to always -use MELPA Stable by adding this to your Emacs initialization: +MELPA Stable contains packages released from our tags. -### Manual +### Via use-package -You can install `Elixir-Mode` manually by placing `Elixir-Mode` on your `load-path` and -`require` ing it. Many people favour the folder `~/.emacs.d/vendor`. +Since Emacs 29, `use-package` is a built-in feature. For versions prior to 29 +one can also install it from MELPA (and MELPA Stable). -```el -(add-to-list 'load-path "~/.emacs.d/vendor") -(require 'elixir-mode) +To install elixir-mode using `use-package` one can: + +``` elisp +(use-package elixir-mode + :ensure t) ``` ## Usage @@ -141,20 +131,17 @@ This package is tested only with a single version of OTP and 3 versions of Elixi ## Elixir Tooling Integration -If you looking for elixir tooling integration for Emacs, check: [alchemist.el](https://github.com/tonini/alchemist.el) - You can use [web-mode.el](http://web-mode.org) to edit elixir templates (eex files). [mix.el](https://github.com/ayrat555/mix.el) provides a minor mode for integration with Mix, a build tool that ships with Elixir. +[exunit.el](https://github.com/ananthakumaran/exunit.el) provides `ExUnit` integration. ## Elixir Format -``` elisp -M-x elixir-format -``` +This mode can call mix for formatting code. When inside an elixir buffer, just type `M-x elixir-format`. -### Add elixir-mode hook to run elixir format on file save +To automate that, you can add this command to the `before-save` hook. ``` elisp ;; Create a buffer-local hook to run elixir-format on save, only when we enable elixir-mode. @@ -180,16 +167,91 @@ or you set `elixir-format-arguments` in a hook like this: ``` In this example we use [Projectile](https://github.com/bbatsov/projectile) to determine if we are in a project and then set `elixir-format-arguments` accordingly. + Please note that this code snippet may cause unhappiness if there is no `.formatter.exs` file available. -## Treesitter Support +## Tips & Tricks + +### Prettify symbols + +Emacs supports [font ligatures](https://en.wikipedia.org/wiki/Ligature_(writing)). For enabling it for Elixir +you can add it to your configuration: -There is a work-in-progress mode that uses Tree-Sitter instead of SMIE. If you are on Emacs 29.x you can try it out [wkirschbaum/elixir-ts-mode](https://github.com/wkirschbaum/elixir-ts-mode). +``` elisp +(add-hook + 'elixir-mode-hook + (lambda () + (push '(">=" . ?\u2265) prettify-symbols-alist) + (push '("<=" . ?\u2264) prettify-symbols-alist) + (push '("!=" . ?\u2260) prettify-symbols-alist) + (push '("==" . ?\u2A75) prettify-symbols-alist) + (push '("=~" . ?\u2245) prettify-symbols-alist) + (push '("<-" . ?\u2190) prettify-symbols-alist) + (push '("->" . ?\u2192) prettify-symbols-alist) + (push '("<-" . ?\u2190) prettify-symbols-alist) + (push '("|>" . ?\u25B7) prettify-symbols-alist))) + +;; Or if you use use-packge + +(use-package elixir-mode + :hook (elixir-mode . (lambda () + (push '(">=" . ?\u2265) prettify-symbols-alist) + (push '("<=" . ?\u2264) prettify-symbols-alist) + (push '("!=" . ?\u2260) prettify-symbols-alist) + (push '("==" . ?\u2A75) prettify-symbols-alist) + (push '("=~" . ?\u2245) prettify-symbols-alist) + (push '("<-" . ?\u2190) prettify-symbols-alist) + (push '("->" . ?\u2192) prettify-symbols-alist) + (push '("<-" . ?\u2190) prettify-symbols-alist) + (push '("|>" . ?\u25B7) prettify-symbols-alist)))) +``` + +### Formatting + +If you have issues with the formatter provided by this package, you can try +using the format function of language servers. Elixir-ls supports this. + +One way to configure this with `eglot` and `use-package` would be: + +``` elisp +(use-package elixir-mode + :hook (elixir-mode . eglot-ensure) + (before-save . eglot-format)) +``` + +### Syntax highlighting for LiveView (and similar techniques for other syntaxes) + +When you need different major modes in the SAME buffer, Emacs do not provide a standard way. +There is an external package that can help here by adding more than one major mode called `poly-mode`. + +A possible configuration would be: + +``` elisp +;; Assumes web-mode and elixir-mode are already set up +;; +(use-package polymode + :mode ("\.ex$" . poly-elixir-web-mode) + :config + (define-hostmode poly-elixir-hostmode :mode 'elixir-mode) + (define-innermode poly-liveview-expr-elixir-innermode + :mode 'web-mode + :head-matcher (rx line-start (* space) "~H" (= 3 (char "\"'")) line-end) + :tail-matcher (rx line-start (* space) (= 3 (char "\"'")) line-end) + :head-mode 'host + :tail-mode 'host + :allow-nested nil + :keep-in-mode 'host + :fallback-mode 'host) + (define-polymode poly-elixir-web-mode + :hostmode 'poly-elixir-hostmode + :innermodes '(poly-liveview-expr-elixir-innermode)) + ) +(setq web-mode-engines-alist '(("elixir" . "\\.ex\\'"))) +``` ## History -This mode is based on the -[Emacs mode by secondplanet](https://github.com/secondplanet/elixir-mode). +This mode is based on the [Emacs mode by secondplanet](https://github.com/secondplanet/elixir-mode). ## Contributing @@ -197,8 +259,7 @@ Please read [CONTRIBUTING.md](https://github.com/elixir-editors/emacs-elixir/blo ## License -Copyright © 2011-2017 Samuel Tonini, Matt DeBoard, Andreas Fuchs, secondplanet and -[contributors](https://github.com/elixir-editors/emacs-elixir/contributors). +Copyright © 2011-2017 Samuel Tonini, Matt DeBoard, Andreas Fuchs, secondplanet and [contributors](https://github.com/elixir-editors/emacs-elixir/contributors). Distributed under the GNU General Public License, version 3