2016-10-11 21:05:12 +00:00
|
|
|
# Asynchronous Lint Engine [![Build Status](https://travis-ci.org/w0rp/ale.svg?branch=master)](https://travis-ci.org/w0rp/ale)
|
2016-10-11 20:55:26 +00:00
|
|
|
|
|
|
|
![ALE Logo by Mark Grealish - https://www.bhalash.com/](img/logo.jpg?raw=true)
|
2016-09-08 23:23:26 +00:00
|
|
|
|
|
|
|
ALE (Asynchronous Lint Engine) is a plugin for providing linting in NeoVim
|
|
|
|
and Vim 8 while you edit your text files.
|
|
|
|
|
2016-10-07 16:48:47 +00:00
|
|
|
![linting example](img/example.gif?raw=true)
|
2016-10-04 21:38:43 +00:00
|
|
|
|
2016-09-08 23:23:26 +00:00
|
|
|
ALE makes use of NeoVim and Vim 8 job control functions and timers to
|
|
|
|
run linters on the contents of text buffers and return errors as
|
|
|
|
text is changed in Vim. This allows for displaying warnings and
|
2016-09-13 22:18:52 +00:00
|
|
|
errors in files being edited in Vim before files have been saved
|
|
|
|
back to a filesystem.
|
|
|
|
|
|
|
|
In other words, this plugin allows you to lint while you type.
|
2016-09-08 23:23:26 +00:00
|
|
|
|
2016-10-25 09:39:06 +00:00
|
|
|
## Table of Contents
|
|
|
|
|
2016-10-25 09:44:50 +00:00
|
|
|
1. [Supported Languages and Tools](#supported-languages)
|
|
|
|
2. [Usage](#usage)
|
|
|
|
3. [Installation](#installation)
|
|
|
|
1. [Installation with Pathogen](#installation-with-pathogen)
|
|
|
|
2. [Installation with Vundle](#installation-with-vundle)
|
|
|
|
3. [Manual Installation](#manual-installation)
|
|
|
|
4. [FAQ](#faq)
|
|
|
|
1. [How do I disable particular linters?](#faq-disable-linters)
|
|
|
|
2. [How can I keep the sign gutter open?](#faq-disable-linters)
|
|
|
|
3. [How can I change the signs ALE uses?](#faq-change-signs)
|
|
|
|
4. [How can I show errors or warnings in my statusline?](#faq-statusline)
|
|
|
|
5. [How can I change the format for echo messages?](#faq-echo-format)
|
|
|
|
6. [How can I execute some code when ALE stops linting?](#faq-autocmd)
|
2016-10-24 21:09:41 +00:00
|
|
|
7. [How can I navigate between errors quickly?](#faq-navigation)
|
2016-10-25 09:39:06 +00:00
|
|
|
|
|
|
|
<a name="supported-languages"></a>
|
|
|
|
|
|
|
|
## 1. Supported Languages and Tools
|
2016-09-19 21:19:21 +00:00
|
|
|
|
|
|
|
This plugin supports the following languages and tools. All available
|
|
|
|
tools will be run in combination, so they can be complementary.
|
|
|
|
|
|
|
|
<!--
|
|
|
|
Keep the table rows sorted alphabetically by the language name,
|
|
|
|
and the tools in the tools column sorted alphabetically by the tool
|
|
|
|
name. That seems to be the fairest way to arrange this table.
|
|
|
|
-->
|
|
|
|
|
|
|
|
| Language | Tools |
|
|
|
|
| -------- | ----- |
|
2016-10-20 14:26:56 +00:00
|
|
|
| Ansible | [ansible-lint](https://github.com/willthames/ansible-lint) |
|
2016-10-03 22:43:54 +00:00
|
|
|
| Bash | [-n flag](https://www.gnu.org/software/bash/manual/bash.html#index-set), [shellcheck](https://www.shellcheck.net/) |
|
2016-10-03 12:18:27 +00:00
|
|
|
| Bourne Shell | [-n flag](http://linux.die.net/man/1/sh), [shellcheck](https://www.shellcheck.net/) |
|
2016-10-31 05:32:39 +00:00
|
|
|
| C | [cppcheck](http://cppcheck.sourceforge.net), [gcc](https://gcc.gnu.org/), [clang](http://clang.llvm.org/)|
|
2016-10-20 14:26:56 +00:00
|
|
|
| C++ (filetype cpp) | [cppcheck] (http://cppcheck.sourceforge.net), [gcc](https://gcc.gnu.org/)|
|
2016-10-30 18:23:32 +00:00
|
|
|
| Chef | [foodcritic](http://www.foodcritic.io/) |
|
2016-10-08 15:52:23 +00:00
|
|
|
| CoffeeScript | [coffee](http://coffeescript.org/), [coffeelint](https://www.npmjs.com/package/coffeelint) |
|
2016-10-07 20:33:16 +00:00
|
|
|
| CSS | [csslint](http://csslint.net/) |
|
|
|
|
| Cython (pyrex filetype) | [cython](http://cython.org/) |
|
2016-09-19 21:19:21 +00:00
|
|
|
| D | [dmd](https://dlang.org/dmd-linux.html)^ |
|
2016-10-16 15:44:09 +00:00
|
|
|
| Elixir | [credo](https://github.com/rrrene/credo) |
|
2016-09-19 21:19:21 +00:00
|
|
|
| Fortran | [gcc](https://gcc.gnu.org/) |
|
2016-10-11 11:57:42 +00:00
|
|
|
| Go | [gofmt -e](https://golang.org/cmd/gofmt/), [go vet](https://golang.org/cmd/vet/), [golint](https://godoc.org/github.com/golang/lint) |
|
2016-10-19 12:27:03 +00:00
|
|
|
| Haskell | [ghc](https://www.haskell.org/ghc/), [hlint](https://hackage.haskell.org/package/hlint) |
|
2016-10-08 15:01:03 +00:00
|
|
|
| HTML | [HTMLHint](http://htmlhint.com/), [tidy](http://www.html-tidy.org/) |
|
2016-11-01 09:00:08 +00:00
|
|
|
| JavaScript | [eslint](http://eslint.org/), [jscs](http://jscs.info/), [jshint](http://jshint.com/), [FlowType](https://flowtype.org/) |
|
2016-10-03 22:36:19 +00:00
|
|
|
| JSON | [jsonlint](http://zaa.ch/jsonlint/) |
|
2016-10-12 14:44:53 +00:00
|
|
|
| Lua | [luacheck](https://github.com/mpeterv/luacheck) |
|
2016-10-24 19:40:24 +00:00
|
|
|
| Markdown | [mdl](https://github.com/mivok/markdownlint) |
|
2016-10-24 19:32:52 +00:00
|
|
|
| MATLAB | [mlint](https://www.mathworks.com/help/matlab/ref/mlint.html) |
|
2016-11-23 15:19:36 +00:00
|
|
|
| OCaml | [merlin](https://github.com/the-lambda-church/merlin) see `:help ale-integration-ocaml-merlin` for configuration instructions
|
2016-10-09 15:31:03 +00:00
|
|
|
| Perl | [perl -c](https://perl.org/), [perl-critic](https://metacpan.org/pod/Perl::Critic) |
|
2016-10-06 10:05:48 +00:00
|
|
|
| PHP | [php -l](https://secure.php.net/), [phpcs](https://github.com/squizlabs/PHP_CodeSniffer) |
|
2016-10-07 21:16:29 +00:00
|
|
|
| Pug | [pug-lint](https://github.com/pugjs/pug-lint) |
|
2016-10-30 09:47:06 +00:00
|
|
|
| Python | [flake8](http://flake8.pycqa.org/en/latest/), [pylint](https://www.pylint.org/) |
|
2016-10-16 15:44:09 +00:00
|
|
|
| Ruby | [rubocop](https://github.com/bbatsov/rubocop) |
|
2016-10-05 09:38:38 +00:00
|
|
|
| SASS | [sass-lint](https://www.npmjs.com/package/sass-lint) |
|
|
|
|
| SCSS | [sass-lint](https://www.npmjs.com/package/sass-lint), [scss-lint](https://github.com/brigade/scss-lint) |
|
2016-10-07 15:28:44 +00:00
|
|
|
| Scala | [scalac](http://scala-lang.org) |
|
2016-11-10 16:24:17 +00:00
|
|
|
| TypeScript | [tslint](https://github.com/palantir/tslint), typecheck |
|
2016-10-08 12:38:31 +00:00
|
|
|
| Verilog | [iverilog](https://github.com/steveicarus/iverilog), [verilator](http://www.veripool.org/projects/verilator/wiki/Intro) |
|
2016-10-07 20:33:16 +00:00
|
|
|
| Vim | [vint](https://github.com/Kuniwak/vint) |
|
|
|
|
| YAML | [yamllint](https://yamllint.readthedocs.io/) |
|
2016-09-19 21:19:21 +00:00
|
|
|
|
|
|
|
*^ Supported only on Unix machines via a wrapper script.*
|
|
|
|
|
|
|
|
If you would like to see support for more languages and tools, please
|
|
|
|
[create an issue](https://github.com/w0rp/ale/issues)
|
|
|
|
or [create a pull request](https://github.com/w0rp/ale/pulls).
|
|
|
|
If your tool can read from stdin or you have code to suggest which is good,
|
|
|
|
support can be happily added for more tools.
|
|
|
|
|
2016-10-25 09:39:06 +00:00
|
|
|
<a name="usage"></a>
|
|
|
|
|
|
|
|
## 2. Usage
|
2016-09-19 21:19:21 +00:00
|
|
|
|
|
|
|
Once this plugin is installed, while editing your files in supported
|
|
|
|
languages and tools which have been correctly installed,
|
|
|
|
this plugin will send the contents of your text buffers to a variety of
|
|
|
|
programs for checking the syntax and semantics of your programs. By default,
|
|
|
|
linters will be re-run in the background to check your syntax when you open
|
|
|
|
new buffers or as you make edits to your files.
|
|
|
|
|
2016-10-25 09:39:06 +00:00
|
|
|
The behaviour of linting can be configured with a variety of options,
|
|
|
|
documented in [the Vim help file](doc/ale.txt). For more information on the
|
|
|
|
options ALE offers, consult `:help ale-options` for global options and `:help
|
|
|
|
ale-linter-options` for options specified to particular linters.
|
|
|
|
|
|
|
|
<a name="installation"></a>
|
|
|
|
|
|
|
|
## 3. Installation
|
|
|
|
|
|
|
|
To install this plugin, you should use one of the following methods.
|
|
|
|
For Windows users, replace usage of the Unix `~/.vim` directory with
|
|
|
|
`%USERPROFILE%\_vim`, or another directory if you have configured
|
|
|
|
Vim differently. On Windows, your `~/.vimrc` file will be similarly
|
|
|
|
stored in `%USERPROFILE%\_vimrc`.
|
|
|
|
|
|
|
|
<a name="installation-with-pathogen"></a>
|
|
|
|
|
2016-10-25 09:44:50 +00:00
|
|
|
### 3.i. Installation with Pathogen
|
2016-10-25 09:39:06 +00:00
|
|
|
|
|
|
|
To install this module with [Pathogen](https://github.com/tpope/vim-pathogen),
|
|
|
|
you should clone this repository to your bundle directory, and ensure
|
|
|
|
you have the line `execute pathogen#infect()` in your `~/.vimrc` file.
|
|
|
|
You can run the following commands in your terminal to do so:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
cd ~/.vim/bundle
|
|
|
|
git clone https://github.com/w0rp/ale.git
|
|
|
|
```
|
|
|
|
|
|
|
|
<a name="installation-with-vundle"></a>
|
|
|
|
|
2016-10-25 09:44:50 +00:00
|
|
|
### 3.ii. Installation with Vundle
|
2016-10-25 09:39:06 +00:00
|
|
|
|
|
|
|
You can install this plugin using [Vundle](https://github.com/VundleVim/Vundle.vim)
|
|
|
|
by using the path on GitHub for this repository.
|
|
|
|
|
|
|
|
```vim
|
|
|
|
Plugin 'w0rp/ale'
|
|
|
|
```
|
|
|
|
|
|
|
|
See the Vundle documentation for more information.
|
|
|
|
|
|
|
|
<a name="manual-installation"></a>
|
|
|
|
|
2016-10-25 09:44:50 +00:00
|
|
|
### 3.iii. Manual Installation
|
2016-10-25 09:39:06 +00:00
|
|
|
|
|
|
|
For installation without a package manager, you can clone this git repository
|
|
|
|
into a bundle directory as with pathogen, and add the repository to your
|
|
|
|
runtime path yourself. First clone the repository.
|
|
|
|
|
|
|
|
```bash
|
|
|
|
cd ~/.vim/bundle
|
|
|
|
git clone https://github.com/w0rp/ale.git
|
|
|
|
```
|
|
|
|
|
|
|
|
Then, modify your `~/.vimrc` file to add this plugin to your runtime path.
|
|
|
|
|
|
|
|
```vim
|
|
|
|
set nocompatible
|
|
|
|
filetype off
|
|
|
|
|
|
|
|
let &runtimepath.=',~/.vim/bundle/ale'
|
|
|
|
|
|
|
|
filetype plugin on
|
|
|
|
```
|
|
|
|
|
|
|
|
You can add the following line to generate documentation tags automatically,
|
|
|
|
if you don't have something similar already, so you can use the `:help` command
|
|
|
|
to consult ALE's online documentation:
|
|
|
|
|
|
|
|
```vim
|
|
|
|
silent! helptags ALL
|
|
|
|
```
|
|
|
|
|
|
|
|
Because the author of this plugin is a weird nerd, this is his preferred
|
|
|
|
installation method.
|
|
|
|
|
|
|
|
<a name="faq"></a>
|
|
|
|
|
|
|
|
## 4. FAQ
|
|
|
|
|
|
|
|
<a name="faq-disable-linters"></a>
|
|
|
|
|
2016-10-25 09:44:50 +00:00
|
|
|
### 4.i. How do I disable particular linters?
|
2016-09-19 21:19:21 +00:00
|
|
|
|
|
|
|
By default, all available tools for all supported languages will be run.
|
|
|
|
If you want to only select a subset of the tools, simply create a
|
|
|
|
`g:ale_linters` dictionary in your vimrc file mapping filetypes
|
|
|
|
to lists of linters to run.
|
|
|
|
|
|
|
|
```vim
|
|
|
|
let g:ale_linters = {
|
|
|
|
\ 'javascript': ['eslint'],
|
|
|
|
\}
|
|
|
|
```
|
|
|
|
|
|
|
|
For all languages unspecified in the dictionary, all possible linters will
|
|
|
|
be run for those languages, just as when the dictionary is not defined.
|
|
|
|
Running many linters should not typically obstruct editing in Vim,
|
|
|
|
as they will all be executed in separate processes simultaneously.
|
|
|
|
|
|
|
|
This plugin will look for linters in the [`ale_linters`](ale_linters) directory.
|
|
|
|
Each directory within corresponds to a particular filetype in Vim, and each file
|
|
|
|
in each directory corresponds to the name of a particular linter.
|
|
|
|
|
2016-10-25 09:39:06 +00:00
|
|
|
<a name="faq-keep-signs"></a>
|
2016-10-02 08:22:24 +00:00
|
|
|
|
2016-10-25 09:44:50 +00:00
|
|
|
### 4.ii. How can I keep the sign gutter open?
|
2016-10-25 09:39:06 +00:00
|
|
|
|
|
|
|
You can keep the sign gutter open at all times by setting the
|
|
|
|
`g:ale_sign_column_always` to 1
|
2016-09-26 14:55:26 +00:00
|
|
|
|
|
|
|
```vim
|
|
|
|
let g:ale_sign_column_always = 1
|
|
|
|
```
|
|
|
|
|
2016-10-25 09:39:06 +00:00
|
|
|
<a name="faq-change-signs"></a>
|
|
|
|
|
2016-10-25 09:44:50 +00:00
|
|
|
### 4.iii. How can I change the signs ALE uses?
|
2016-10-02 08:22:24 +00:00
|
|
|
|
|
|
|
Use these options to specify what text should be used for signs:
|
|
|
|
|
|
|
|
```vim
|
|
|
|
let g:ale_sign_error = '>>'
|
|
|
|
let g:ale_sign_warning = '--'
|
|
|
|
```
|
|
|
|
|
2016-10-25 09:39:06 +00:00
|
|
|
<a name="faq-statusline"></a>
|
|
|
|
|
2016-10-25 09:44:50 +00:00
|
|
|
### 4.iv. How can I show errors or warnings in my statusline?
|
2016-10-07 16:48:47 +00:00
|
|
|
|
2016-10-07 17:34:23 +00:00
|
|
|
You can use `ALEGetStatusLine()` to integrate ALE into vim statusline.
|
2016-10-07 16:48:47 +00:00
|
|
|
To enable it, you should have in your `statusline` settings
|
|
|
|
|
|
|
|
```vim
|
|
|
|
%{ALEGetStatusLine()}
|
|
|
|
```
|
|
|
|
|
2016-10-07 17:34:23 +00:00
|
|
|
When errors are detected a string showing the number of errors will be shown.
|
2016-10-07 16:48:47 +00:00
|
|
|
You can customize the output format using the global list `g:ale_statusline_format` where:
|
|
|
|
|
|
|
|
- The 1st element is for errors
|
|
|
|
- The 2nd element is for warnings
|
2016-10-07 17:34:23 +00:00
|
|
|
- The 3rd element is for when no errors are detected
|
2016-10-07 16:48:47 +00:00
|
|
|
|
|
|
|
e.g
|
|
|
|
|
|
|
|
```vim
|
|
|
|
let g:ale_statusline_format = ['⨉ %d', '⚠ %d', '⬥ ok']
|
|
|
|
```
|
|
|
|
|
2016-10-07 17:34:23 +00:00
|
|
|
![Statusline with issues](img/issues.png)
|
2016-10-07 16:48:47 +00:00
|
|
|
![Statusline with no issues](img/no_issues.png)
|
|
|
|
|
2016-10-25 09:39:06 +00:00
|
|
|
<a name="faq-echo-format"></a>
|
2016-10-10 11:53:54 +00:00
|
|
|
|
2016-10-25 09:44:50 +00:00
|
|
|
### 4.v. How can I change the format for echo messages?
|
2016-10-10 11:53:54 +00:00
|
|
|
|
|
|
|
There are 3 global options that allow customizing the echoed message.
|
|
|
|
|
|
|
|
- `g:ale_echo_msg_format` where:
|
|
|
|
* `%s` is the error message itself
|
|
|
|
* `%linter%` is the linter name
|
|
|
|
* `%severity` is the severity type
|
|
|
|
- `g:ale_echo_msg_error_str` is the string used for error severity.
|
|
|
|
- `g:ale_echo_msg_warning_str` is the string used for warning severity.
|
|
|
|
|
|
|
|
So for example this:
|
|
|
|
|
|
|
|
```vim
|
|
|
|
let g:ale_echo_msg_error_str = 'E'
|
2016-10-10 14:53:09 +00:00
|
|
|
let g:ale_echo_msg_warning_str = 'W'
|
|
|
|
let g:ale_echo_msg_format = '[%linter%] %s [%severity%]'
|
2016-10-10 11:53:54 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
Will give you:
|
|
|
|
|
|
|
|
![Echoed message](img/echo.png)
|
|
|
|
|
2016-10-25 09:39:06 +00:00
|
|
|
<a name="faq-autocmd"></a>
|
2016-09-19 21:04:11 +00:00
|
|
|
|
2016-10-25 09:44:50 +00:00
|
|
|
### 4.vi. How can I execute some code when ALE stops linting?
|
2016-09-19 21:04:11 +00:00
|
|
|
|
2016-10-25 09:39:06 +00:00
|
|
|
ALE runs its own [autocmd](http://vimdoc.sourceforge.net/htmldoc/autocmd.html)
|
|
|
|
event whenever has a linter has been successfully executed and processed. This
|
|
|
|
autocmd event can be used to call arbitrary functions after ALE stops linting.
|
2016-09-19 21:04:11 +00:00
|
|
|
|
|
|
|
```vim
|
2016-10-25 09:39:06 +00:00
|
|
|
augroup YourGroup
|
|
|
|
autocmd!
|
2016-10-25 14:46:18 +00:00
|
|
|
autocmd User ALELint call YourFunction()
|
2016-10-25 09:39:06 +00:00
|
|
|
augroup END
|
2016-09-19 21:04:11 +00:00
|
|
|
```
|
2016-10-24 21:09:41 +00:00
|
|
|
|
|
|
|
<a name="faq-navigation"></a>
|
|
|
|
|
|
|
|
### 4.vii. How can I navigate between errors quickly?
|
|
|
|
|
|
|
|
ALE offers some commands with `<Plug>` keybinds for moving between warnings and
|
|
|
|
errors quickly. You can map the keys Ctrl+j and Ctrl+k to moving between errors
|
|
|
|
for example:
|
|
|
|
|
|
|
|
```vim
|
|
|
|
nmap <silent> <C-k> <Plug>(ale_previous_wrap)
|
|
|
|
nmap <silent> <C-j> <Plug>(ale_next_wrap)
|
|
|
|
```
|
|
|
|
|
|
|
|
For more information, consult the online documentation with
|
|
|
|
`:help ale-navigation-commands`.
|