elm-format
elm-format
is still in beta. If you run into any problems, please report them.The format produced by elm-format may change significantly before the 1.0.0 release. If this will cause problems for you, please refrain from using elm-format during the beta-test period.
elm-format
formats Elm source code according to a standard set of rules based on the official Elm Style Guide. It is inspired by the popular gofmt.
The benefits of elm-format
:
- It makes code easier to write, because you never have to worry about minor formatting concerns while powering out new code.
- It makes code easier to read, because there are no longer distracting minor stylistic differences between different code bases. As such, your brain can map more efficiently from source to mental model.
- It makes code easier to maintain, because you can no longer have diffs related only to formatting; every diff necessarily involves a material change.
- It saves your team time debating how to format things, because there is a standard tool that formats everything the same way.
- It saves you time because you don't have to nitpick over formatting details of your code.
Usage
elm-format Main.elm # Format a single file
elm-format Main.elm --yes # Overwrite the file without prompting
elm-format src/ # Format all *.elm files in a directory
elm-format --stdin # Format input from stdin and write to stdout
elm-format --stdin --output Main.elm # Format input from stdin and write to file
elm-format --help # See other command line options
Installation
elm-format
is still in beta. If you run into any problems, please report them.The format produced by elm-format may change significantly before the 1.0.0 release. If this will cause problems for you, please refrain from using elm-format during the beta-test period.
To install elm-format
for Elm 0.19:
npm install -g elm-format
or download the version appropriate for your OS from the release page,
unzip it,
and place elm-format
or elm-format.exe
(windows) on your PATH
.
To use elm-format
with Elm 0.18, either pass the --elm-version=0.18
when running elm-format
,
or use the *-0.18-*
binaries available from the release page.
Editor integration
Find your editor in the table below. The recommended plugin for each editor is indicated with 🏆 (trophy emoji).
Editor | Plugin | Installation | Formatting | Format on save | Configuration | Error handling |
---|---|---|---|---|---|---|
Atom | 🏆 atom-elm-format | ✅ 2 steps | ✅ | ✅ | ✅ | |
atom-beautify | ✅ | ✅ | ✅ | |||
Light Table | 🏆 elm-light | ✅ | ✅ | |||
Vim | 🏆 elm-vim | ❌ 6 steps | ✅ | ✅ | ❌ no error message | |
Emacs | 🏆 elm-mode | ❌ 4 steps | ✅ | ✅ | ||
Visual Studio Code | 🏆 Elm Language Support | ✅ | ❔ TBD | ❔ TBD | ||
Sublime Text | 🏆 Elm Language Support | ✅ 2 steps | ❔ TBD | ✅ | ❔ TBD | ❔ TBD |
JetBrains (WebStorm, etc) | 🏆 Elm Language Plugin | ❔ TBD | ✅ | ❔ TBD | ❔ TBD | |
TextMate | 🏆 Elm.tmbundle | ✅ 2 steps | ❔ TBD | ❔ TBD | ❔ TBD | ❔ TBD |
Detailed instructions
If you can simplify or improve the installation instructions or add instructions for another editor, please make a pull request.
The default behavior of elm-format
-approved plugins is to format Elm files on save.
atom-elm-format installation
-
Install elm-format
-
Install atom-elm-format
apm install elm-format
or use the Atom package manager in Atom's settings
atom-beautify installation
-
Install elm-format
-
Install atom-beautify
apm install atom-beautify
or use the Atom package manager in Atom's settings
- Use
^⌥B
(CTRL-ALT-B
) to format a file
elm-light installation
- Install elm-format
- Install the elm-light plugin using the Light Table plugin manager
- To format on save, edit your user keymap by performing the following:
- Click File -> Settings -> User Keymap to open the user keymap.
- Copy the following line and paste it into your keymap. Anywhere is fine as long as it is whithin the outer brackets. Ensure to save the file.
[:editor.elm "ctrl-s" :save :elm-format :elm.lint]
- Search for "App: Reload keymaps" in the Commands Window to apply the changes (or restart LightTable).
elm-mode installation
-
Install elm-format
-
If your Emacs has
package.el
(which is automatically the case for Emacs >= 24), you can installelm-mode
from the package in MELPA:-
Ensure that you have added the MELPA source in your
~/.emacs.d/init.el
:(require 'package) (add-to-list 'package-archives '("melpa" . "http://melpa.org/packages/"))
-
Install elm-mode (official instructions): Use
M-x list-packages
and chooseelm-mode
.
-
-
Set
elm-format-on-save
tot
to apply elm-format on the current buffer on every save. (The setting can be changed viaM-x customize-variable elm-format-on-save
. Click buttonToggle
to change the setting and buttonState
to activate the setting.)
elm-vim installation
-
Install elm-format
-
Install vim-plug (official instructions)
-
Download vim-plug:
curl -fLo ~/.vim/autoload/plug.vim --create-dirs \ https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim
-
Make sure there is a section like this in your
~/.vimrc
:call plug#begin('~/.vim/plugged') " ... any active plugins call plug#end()
-
-
Install elm-vim (official instructions)
- Add
Plug 'elmcast/elm-vim'
to theplug#begin
plugin section in your~/.vimrc
- Start
vim
and run:PlugInstall
- Add
-
Add the following to your
~/.vimrc
:
let g:elm_format_autosave = 1
Visual Studio Code installation
Note: If you previously installed a VSCode extension called "elm-format", uninstall it (it is deprecated, and the "elm" extension now provides elm-format integration).
-
Install elm-format
-
Install Elm Language Support for VSCode
ext install elm
-
Configure the extension to format on save:
- Go to
Preferences -> Settings
in the menu - In your User Settings, update the following value:
"[elm]": { "editor.formatOnSave": true },
- Go to
Sublime Text installation
- Install elm-format
- Install the Elm Language Support package.
JetBrains installation
This is for WebStorm and other JetBrains IDEs.
- Install elm-format
- Install the Elm Language Plugin package.
- Install the File Watchers plugin (available in the plugin repository)
- Add a file watcher for .elm files with the settings as shown here.
Development info
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
Building from source
brew install haskell-stack
git clone https://github.com/avh4/elm-format.git
cd elm-format
stack setup
stack build
stack install
~/.local/bin/elm-format-0.19 --help
Running tests
brew install shellcheck
./tests/run-tests.sh