Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/avh4/elm-format
elm-format formats Elm source code according to a standard set of rules based on the official Elm Style Guide
https://github.com/avh4/elm-format
code-style elm formatter
Last synced: 25 days ago
JSON representation
elm-format formats Elm source code according to a standard set of rules based on the official Elm Style Guide
- Host: GitHub
- URL: https://github.com/avh4/elm-format
- Owner: avh4
- License: bsd-3-clause
- Created: 2015-09-13T00:09:34.000Z (about 9 years ago)
- Default Branch: main
- Last Pushed: 2023-04-13T18:43:21.000Z (over 1 year ago)
- Last Synced: 2024-10-01T17:42:07.734Z (about 1 month ago)
- Topics: code-style, elm, formatter
- Language: Haskell
- Homepage:
- Size: 3.84 MB
- Stars: 1,311
- Watchers: 25
- Forks: 145
- Open Issues: 226
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-ccamel - avh4/elm-format - elm-format formats Elm source code according to a standard set of rules based on the official Elm Style Guide (Haskell)
README
[](https://travis-ci.org/avh4/elm-format)
[](https://github.com/avh4/elm-format/releases/tag/0.8.7)
# elm-format
`elm-format` formats [Elm](https://elm-lang.org) source code
according to a standard set of rules based on [the official Elm Style Guide](https://elm-lang.org/docs/style-guide).
It is inspired by the popular [gofmt](https://blog.golang.org/go-fmt-your-code).
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
```bash
elm-format . # Format all *.elm files in the current directory
elm-format Main.elm # Format a single file
elm-format Main.elm --yes # Overwrite the file without prompting
elm-format src/ Main.elm # Format the listed files and directories
elm-format --help # See other command line options
```
## Installation [](https://github.com/avh4/elm-format/releases/tag/0.8.7)
To install `elm-format`:
```sh
npm install -g elm-format
```
or download the version appropriate for your OS from the [release page](https://github.com/avh4/elm-format/releases/tag/0.8.7),
unzip it,
and place `elm-format` or `elm-format.exe` (windows) on your `PATH`.
You must run `elm-format` from the directory that contains your `elm.json` (for Elm 0.19) or `elm-package.json` (for Elm 0.18),
or else you must pass the appropriate `--elm-version=0.19`/`--elm-version=0.18` command line argument.
## Editor integration
Find your editor in the table below. The recommended plugin for each editor is indicated with :trophy: (trophy emoji).
Editor
Plugin
Installation
Formatting
Format on save
Configuration
Error handling
Atom
:trophy: atom-elm-format
:white_check_mark: 2 steps
:white_check_mark:
:white_check_mark:
:white_check_mark:
:warning: no installation instructions
atom-beautify
:warning: 3 steps
:white_check_mark:
:warning: requires configuration
:white_check_mark:
:white_check_mark:
Light Table
:trophy: elm-light
:warning: 3 steps
:white_check_mark:
:warning: requires configuration
:white_check_mark:
:warning: no installation instructions
Vim
:trophy: elm-vim
:x: 6 steps
:white_check_mark:
⚠️ requires configuration
:white_check_mark:
:x: no error message
Emacs
:trophy: elm-mode
:x: 4 steps
:white_check_mark:
:warning: requires configuration
:white_check_mark:
:warning: no installation instructions
Visual Studio Code
:trophy: Elm Tooling
:warning: 3 steps
:white_check_mark:
:warning: requires configuration
:white_check_mark:
:x: uninformative error message
Sublime Text
:trophy: Elm Language Support
:white_check_mark: 2 steps
❔ TBD
:white_check_mark:
❔ TBD
❔ TBD
JetBrains (WebStorm, etc)
:trophy: intellij-elm
:warning: 4 steps
:white_check_mark:
:warning: requires configuration
:warning: requires configuration
❔ TBD
TextMate
:trophy: Elm.tmbundle
:white_check_mark: 2 steps
❔ TBD
❔ TBD
❔ TBD
❔ TBD
## Integration with other tools
These tools also integrate with elm-format:
- [Prettier](https://prettier.io/) via [gicentre/prettier-plugin-elm](https://github.com/gicentre/prettier-plugin-elm)
## Detailed installation instructions
If you can simplify or improve the installation instructions or add instructions for another editor, please [make a pull request](https://github.com/avh4/elm-format/edit/master/README.md).
The default behavior of `elm-format`-approved plugins is to format Elm files on save.
### atom-elm-format installation
1. Install elm-format
1. Install atom-elm-format
```
apm install elm-format
```
or use the Atom package manager in Atom's settings
### atom-beautify installation
1. Install elm-format
1. Install atom-beautify
```
apm install atom-beautify
```
or use the Atom package manager in Atom's settings
1. Use `^⌥B` (`CTRL-ALT-B`) to format a file
### elm-light installation
1. Install elm-format
1. Install the [elm-light plugin](https://github.com/rundis/elm-light) using the Light Table plugin manager
1. 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.
```clojure
[: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
1. Install elm-format
1. If your Emacs has `package.el` (which is automatically the case for Emacs >= 24), you can install `elm-mode` from the package in [MELPA](http://melpa.milkbox.net/):
1. Ensure that you have added the MELPA source in your `~/.emacs.d/init.el`:
```lisp
(require 'package)
(add-to-list 'package-archives '("melpa" . "http://melpa.org/packages/"))
```
1. Install elm-mode ([official instructions](https://github.com/jcollard/elm-mode#installation)): Use `M-x list-packages` and choose `elm-mode`.
1. Add the following to your `~/.emacs.d/init.el`:
```lisp
(add-hook 'elm-mode-hook 'elm-format-on-save-mode)
```
### elm-vim installation
> If you are an advanced vim user and already have a preferred vim plugin installation method,
> you may prefer to refer to the [official elm-vim installation instructions](https://github.com/ElmCast/elm-vim#install).
> The instructions below are for those who need a step-by-step walkthrough of how to get the plugin set up.
1. Install elm-format
1. Install [vim-plug](https://github.com/junegunn/vim-plug) ([official instructions](https://github.com/junegunn/vim-plug#installation))
NOTE: if you are using neovim, you will need to refer to the official instructions.
1. Download vim-plug:
```bash
curl -fLo ~/.vim/autoload/plug.vim --create-dirs \
https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim
```
1. Make sure `~/.vimrc` exists and has a section like this:
```vim
call plug#begin('~/.vim/plugged')
" ... any active plugins
call plug#end()
```
1. Install elm-vim ([official instructions](https://github.com/ElmCast/elm-vim#install))
1. Add `Plug 'elmcast/elm-vim'` to the `plug#begin` plugin section in your `~/.vimrc`
1. Start `vim` and run `:PlugInstall`
1. Add the following to your `~/.vimrc`:
```
let g:elm_format_autosave = 1
```
### Visual Studio Code installation
1. Install elm-format
1. Install the extension [Elm Plugin for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=Elmtooling.elm-ls-vscode).
1. Configure the extension to format on save:
1. Find your `settings.json` file ([instructions](https://code.visualstudio.com/docs/getstarted/settings#_settings-file-locations)).
1. Add the following key-value pair to your `settings.json`:
```json
"[elm]": {
"editor.formatOnSave": true
},
```
### Sublime Text installation
1. Install elm-format
1. Install the [Elm Language Support](https://packagecontrol.io/packages/Elm%20Language%20Support) package.
### JetBrains installation
This is for WebStorm and other JetBrains IDEs like IntelliJ and PyCharm.
1. Install elm-format
1. Install the [intellij-elm plugin](https://klazuka.github.io/intellij-elm/)
1. In IntelliJ, open Settings -> Languages & Frameworks -> Elm
1. Specify the path to elm-format (try the "Auto Discover" button first)
1. Check the "Run when file saved?" checkbox
## Development info
Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
Use the instructions below to get started.
More detailed information is available in [`./dev/Documentation/`](./dev/Documentation/).
### Building from source
1. Install Haskell ghcup following the instructions for your operating system: https://www.haskell.org/ghcup/
```bash
# check out the repo
git clone https://github.com/avh4/elm-format.git
cd elm-format
# initial setup
ghcup install ghc 9.4.4
ghcup set ghc 9.4.4
cabal install hpack
# build
dev/build.sh -- build
# run the built elm-format
./_build/bin/elm-format/O0/elm-format
```
See [`dev/Documentation`](dev/Documentation/README.md) for more contributor and build command documentation.