999 lines
41 KiB
Plaintext
999 lines
41 KiB
Plaintext
*ale.txt* For Vim version 8.0.
|
|
*ale*
|
|
|
|
ALE - Asynchronous Lint Engine
|
|
|
|
===============================================================================
|
|
CONTENTS *ale-contents*
|
|
|
|
1. Introduction.........................|ale-introduction|
|
|
2. Supported Languages & Tools..........|ale-support|
|
|
3. Global Options.......................|ale-options|
|
|
4. Linter Options and Recommendations...|ale-linter-options|
|
|
asm...................................|ale-asm-options|
|
|
gcc.................................|ale-asm-gcc|
|
|
c.....................................|ale-c-options|
|
|
clang...............................|ale-c-clang|
|
|
cppcheck............................|ale-c-cppcheck|
|
|
gcc.................................|ale-c-gcc|
|
|
chef..................................|ale-chef-options|
|
|
foodcritic..........................|ale-chef-foodcritic|
|
|
cpp...................................|ale-cpp-options|
|
|
clang...............................|ale-cpp-clang|
|
|
clangtidy...........................|ale-cpp-clangtidy|
|
|
cppcheck............................|ale-cpp-cppcheck|
|
|
gcc.................................|ale-cpp-gcc|
|
|
css...................................|ale-css-options|
|
|
stylelint...........................|ale-css-stylelint|
|
|
cmake.................................|ale-cmake-options|
|
|
cmakelint...........................|ale-cmake-cmakelint|
|
|
erlang................................|ale-erlang-options|
|
|
erlc................................|ale-erlang-erlc|
|
|
fortran...............................|ale-fortran-options|
|
|
gcc.................................|ale-fortran-gcc|
|
|
go....................................|ale-go-options|
|
|
gometalinter........................|ale-go-gometalinter|
|
|
handlebars............................|ale-handlebars-options|
|
|
ember-template-lint.................|ale-handlebars-embertemplatelint|
|
|
html..................................|ale-html-options|
|
|
htmlhint............................|ale-html-htmlhint|
|
|
tidy................................|ale-html-tidy|
|
|
java..................................|ale-java-options|
|
|
checkstyle..........................|ale-java-checkstyle|
|
|
javac...............................|ale-java-javac|
|
|
javascript............................|ale-javascript-options|
|
|
eslint..............................|ale-javascript-eslint|
|
|
flow................................|ale-javascript-flow|
|
|
jshint..............................|ale-javascript-jshint|
|
|
standard............................|ale-javascript-standard|
|
|
xo..................................|ale-javascript-xo|
|
|
kotlin................................|ale-kotlin-options|
|
|
kotlinc.............................|ale-kotlin-kotlinc|
|
|
lua...................................|ale-lua-options|
|
|
luacheck............................|ale-lua-luacheck|
|
|
ocaml.................................|ale-ocaml-options|
|
|
merlin..............................|ale-ocaml-merlin|
|
|
perl..................................|ale-perl-options|
|
|
perl................................|ale-perl-perl|
|
|
php...................................|ale-php-options|
|
|
phpcs...............................|ale-php-phpcs|
|
|
phpmd...............................|ale-php-phpmd|
|
|
python................................|ale-python-options|
|
|
flake8..............................|ale-python-flake8|
|
|
mypy................................|ale-python-mypy|
|
|
pylint..............................|ale-python-pylint|
|
|
ruby..................................|ale-ruby-options|
|
|
reek................................|ale-ruby-reek|
|
|
rubocop.............................|ale-ruby-rubocop|
|
|
rust..................................|ale-rust-options|
|
|
cargo...............................|ale-rust-cargo|
|
|
rustc...............................|ale-rust-rustc|
|
|
sass..................................|ale-sass-options|
|
|
stylelint...........................|ale-sass-stylelint|
|
|
scss..................................|ale-scss-options|
|
|
stylelint...........................|ale-scss-stylelint|
|
|
sh....................................|ale-sh-options|
|
|
shell...............................|ale-sh-shell|
|
|
shellcheck..........................|ale-sh-shellcheck|
|
|
spec..................................|ale-spec-options|
|
|
rpmlint.............................|ale-spec-rpmlint|
|
|
tex...................................|ale-tex-options|
|
|
chktex..............................|ale-tex-chktex|
|
|
lacheck.............................|ale-tex-lacheck|
|
|
typescript............................|ale-typescript-options|
|
|
tslint..............................|ale-typescript-tslint|
|
|
vim...................................|ale-vim-options|
|
|
vint................................|ale-vim-vint|
|
|
yaml..................................|ale-yaml-options|
|
|
yamllint............................|ale-yaml-yamllint|
|
|
5. Commands/Keybinds....................|ale-commands|
|
|
6. API..................................|ale-api|
|
|
7. Special Thanks.......................|ale-special-thanks|
|
|
8. Contact..............................|ale-contact|
|
|
|
|
===============================================================================
|
|
1. Introduction *ale-introduction*
|
|
|
|
ALE provides the means to run linters asynchronously in Vim in a variety of
|
|
languages and tools. ALE sends the contents of buffers to linter programs
|
|
using the |job-control| features available in Vim 8 and NeoVim. For Vim 8,
|
|
Vim must be compiled with the |job| and |channel| and |timer| features
|
|
as a minimum.
|
|
|
|
ALE supports the following key features:
|
|
|
|
1. Running linters when text is changed.
|
|
2. Running linters when files are opened.
|
|
3. Running linters when files are saved. (When a global flag is set.)
|
|
4. Populating the |loclist| with warning and errors.
|
|
5. Setting |signs| with warnings and errors for error markers.
|
|
6. Using |echo| to show error messages when the cursor moves.
|
|
|
|
===============================================================================
|
|
2. Supported Languages & Tools *ale-support*
|
|
|
|
The following languages and tools are supported.
|
|
|
|
* ASM: 'gcc'
|
|
* Ansible: 'ansible-lint'
|
|
* Asciidoc: 'proselint'
|
|
* Bash: 'shell' (-n flag), 'shellcheck'
|
|
* Bourne Shell: 'shell' (-n flag), 'shellcheck'
|
|
* C: 'cppcheck', 'gcc', 'clang'
|
|
* C++ (filetype cpp): 'clang', 'clangtidy', 'cppcheck', 'gcc'
|
|
* C#: 'mcs'
|
|
* Chef: 'foodcritic'
|
|
* CMake: 'cmakelint'
|
|
* CoffeeScript: 'coffee', 'coffelint'
|
|
* Crystal: 'crystal'
|
|
* CSS: 'csslint', 'stylelint'
|
|
* Cython (pyrex filetype): 'cython'
|
|
* D: 'dmd'
|
|
* Dockerfile: 'hadolint'
|
|
* Elixir: 'credo', 'dogma'
|
|
* Elm: 'elm-make'
|
|
* Erlang: 'erlc'
|
|
* Fortran: 'gcc'
|
|
* Go: 'gofmt', 'go vet', 'golint', 'go build', 'gosimple', 'staticcheck'
|
|
* Haml: 'hamllint'
|
|
* Handlebars: 'ember-template-lint'
|
|
* Haskell: 'ghc', 'ghc-mod', 'hlint', 'hdevtools'
|
|
* HTML: 'HTMLHint', 'proselint', 'tidy'
|
|
* Java: 'javac'
|
|
* JavaScript: 'eslint', 'jscs', 'jshint', 'flow', 'xo'
|
|
* JSON: 'jsonlint'
|
|
* Kotlin: 'kotlinc'
|
|
* LaTeX (tex): 'chktex', 'lacheck', 'proselint'
|
|
* Lua: 'luacheck'
|
|
* Markdown: 'mdl', 'proselint', 'vale'
|
|
* MATLAB: 'mlint'
|
|
* nim: 'nim check'
|
|
* nix: 'nix-instantiate'
|
|
* nroff: 'proselint'
|
|
* OCaml: 'merlin' (see |ale-linter-integration-ocaml-merlin|)
|
|
* Perl: 'perl' (-c flag), 'perlcritic'
|
|
* PHP: 'hack', 'php' (-l flag), 'phpcs', 'phpmd'
|
|
* Pod: 'proselint'
|
|
* Pug: 'pug-lint'
|
|
* Puppet: 'puppet', 'puppet-lint'
|
|
* Python: 'flake8', 'mypy', 'pylint'
|
|
* ReasonML: 'merlin'
|
|
* reStructuredText: 'proselint'
|
|
* RPM spec: 'spec'
|
|
* Rust: 'rustc' (see |ale-integration-rust|)
|
|
* Ruby: 'reek', 'rubocop'
|
|
* SASS: 'sasslint', 'stylelint'
|
|
* SCSS: 'sasslint', 'scsslint', 'stylelint'
|
|
* Scala: 'scalac'
|
|
* Slim: 'slim-lint'
|
|
* SML: 'smlnj'
|
|
* SQL: 'sqlint'
|
|
* Swift: 'swiftlint'
|
|
* Texinfo: 'proselint'
|
|
* Text: 'proselint', 'vale'
|
|
* TypeScript: 'tslint', 'typecheck'
|
|
* Verilog: 'iverilog', 'verilator'
|
|
* Vim: 'vint'
|
|
* Vim help: 'proselint'
|
|
* XHTML: 'proselint'
|
|
* YAML: 'yamllint'
|
|
|
|
===============================================================================
|
|
3. Global Options *ale-options*
|
|
|
|
g:airline#extensions#ale#enabled *g:airline#extensions#ale#enabled*
|
|
|
|
Type: |Number|
|
|
Default: `1`
|
|
|
|
Enables or disables the |airline|'s native extension for ale, which displays
|
|
warnings and errors in the status line, prefixed by
|
|
|airline#extensions#ale#error_symbol| and
|
|
|airline#extensions#ale#warning_symbol|.
|
|
|
|
|
|
g:ale_echo_cursor *g:ale_echo_cursor*
|
|
|
|
Type: |Number|
|
|
Default: `1`
|
|
|
|
When this option is set to `1`, a truncated message will be echoed when a
|
|
cursor is near a warning or error. ALE will attempt to find the warning or
|
|
error at a column nearest to the cursor when the cursor is resting on a line
|
|
which contains a warning or error. This option can be set to `0` to disable
|
|
this behaviour.
|
|
The format of the message can be customizable in |g:ale_echo_msg_format|.
|
|
|
|
|
|
g:ale_echo_msg_error_str *g:ale_echo_msg_error_str*
|
|
|
|
Type: |String|
|
|
Default: `Error`
|
|
|
|
The string used for error severity in the echoed message.
|
|
Note |`g:ale_echo_cursor`| should be set to 1
|
|
Note |`g:ale_echo_msg_format`| should contain the `%severity%` handler
|
|
|
|
|
|
g:ale_echo_msg_format *g:ale_echo_msg_format*
|
|
|
|
Type: |String|
|
|
Default: `%s`
|
|
|
|
This variable defines the format of the echoed message. The `%s` is the
|
|
error message itself, and it can contain the following handlers:
|
|
- `%linter%` for linter's name
|
|
- `%severity%` for the type of severity
|
|
Note |`g:ale_echo_cursor`| should be setted to 1
|
|
|
|
|
|
g:ale_echo_msg_warning_str *g:ale_echo_msg_warning_str*
|
|
|
|
Type: |String|
|
|
Default: `Warning`
|
|
|
|
The string used for warning severity in the echoed message.
|
|
Note |`g:ale_echo_cursor`| should be set to 1
|
|
Note |`g:ale_echo_msg_format`| should contain the `%severity%` handler
|
|
|
|
|
|
g:ale_emit_conflict_warnings *g:ale_emit_conflict_warnings*
|
|
|
|
Type: |Number|
|
|
Default: `1`
|
|
|
|
When set to `0`, ALE will not emit any warnings on startup about conflicting
|
|
plugins. ALE will probably not work if other linting plugins are installed.
|
|
|
|
|
|
g:ale_enabled *g:ale_enabled*
|
|
|
|
Type: |Number|
|
|
Default: `1`
|
|
|
|
When set to `0`, this option will completely disable ALE, such that no
|
|
error checking will be performed, etc. ALE can be toggled on and off with
|
|
the |ALEToggle| command, which changes this option.
|
|
|
|
|
|
g:ale_history_enabled *g:ale_history_enabled*
|
|
|
|
Type: |Number|
|
|
Default: `1`
|
|
|
|
When set to `1`, ALE will remember the last few commands which were run
|
|
for every buffer which is open. This information can be viewed with the
|
|
|ALEInfo| command. The size of the buffer can be controlled with the
|
|
|g:ale_max_buffer_history_size| option.
|
|
|
|
This option can be disabled if storing a command history is not desired.
|
|
|
|
|
|
g:ale_history_log_output *g:ale_history_log_output*
|
|
|
|
Type: |Number|
|
|
Default: `0`
|
|
|
|
When set to `1`, ALE will store the output of commands which have completed
|
|
successfully in the command history, and the output will be displayed when
|
|
using |ALEInfo|.
|
|
|
|
|g:ale_history_enabled| must be set to `1` for this output to be stored or
|
|
printed.
|
|
|
|
ALE will likely consume a lot of memory if this option is on, so it should
|
|
only be used for debugging problems with linters.
|
|
|
|
|
|
g:ale_keep_list_window_open *g:ale_keep_list_window_open*
|
|
|
|
Type: |Number|
|
|
Default: `0`
|
|
|
|
When set to `1`, this option will keep the loclist or quickfix windows
|
|
event after all warnings/errors have been removed for files. By default
|
|
the loclist or quicfix windows will be closed automatically when there
|
|
are no warnings or errors.
|
|
|
|
See: |g:ale_open_list|
|
|
|
|
|
|
g:ale_lint_delay *g:ale_lint_delay*
|
|
|
|
Type: |Number|
|
|
Default: `200`
|
|
|
|
This variable controls the milliseconds delay after which the linters will
|
|
be run after text is changed. This option is only meaningful with the
|
|
|g:ale_lint_on_text_changed| variable set to `always`, `insert`, or `normal`.
|
|
|
|
|
|
g:ale_lint_on_enter *g:ale_lint_on_enter*
|
|
|
|
Type: |Number|
|
|
Default: `1`
|
|
|
|
When this option is set to `1`, the |BufEnter| and |BufRead| events will be
|
|
used to apply linters when buffers are first opened. If this is not desired,
|
|
this variable can be set to `0` in your vimrc file to disable this
|
|
behaviour.
|
|
|
|
|
|
g:ale_lint_on_filetype_changed *g:ale_lint_on_filetype_changed*
|
|
|
|
Type: |Number|
|
|
Default: `1`
|
|
|
|
This option will cause ALE to run whenever the filetype is changed. A short
|
|
delay will be used before linting will be done, so the filetype can be
|
|
changed quickly several times in a row, but resulting in only one lint
|
|
cycle.
|
|
|
|
|
|
g:ale_lint_on_save *g:ale_lint_on_save*
|
|
|
|
Type: |Number|
|
|
Default: `1`
|
|
|
|
This option will make ALE run the linters whenever a file is saved when it
|
|
it set to `1` in your vimrc file. This option can be used in combination
|
|
with the |g:ale_lint_on_enter| and |g:ale_lint_on_text_changed| options to
|
|
make ALE only check files after that have been saved, if that is what is
|
|
desired.
|
|
|
|
|
|
g:ale_lint_on_text_changed *g:ale_lint_on_text_changed*
|
|
|
|
Type: |String|
|
|
Default: `always`
|
|
|
|
By default, ALE will check files with the various supported programs when
|
|
text is changed by using the |TextChanged| event. If this behaviour is not
|
|
desired, then this option can be disabled by setting it to `never`. The
|
|
|g:ale_lint_delay| variable will be used to set a |timer_start()| on a
|
|
delay, and each change to a file will continue to call |timer_stop()| and
|
|
|timer_start()| repeatedly until the timer ticks by, and the linters will be
|
|
run. The checking of files will run in the background, so it should not
|
|
inhibit editing files. This option can also be set to `insert` or `normal`
|
|
to lint when text is changed only in insert or normal mode respectively.
|
|
|
|
|
|
g:ale_lint_on_insert_leave *g:ale_lint_on_insert_leave*
|
|
|
|
Type: |Number|
|
|
Default: `0`
|
|
|
|
This option will make ALE run the linters whenever leaving insert mode when
|
|
it it set to `1` in your vimrc file.
|
|
|
|
|
|
g:ale_linter_aliases *g:ale_linter_aliases*
|
|
*b:ale_linter_aliases*
|
|
Type: |Dictionary|
|
|
Default: `{}`
|
|
|
|
The |g:ale_linter_aliases| option can be used to set aliases from one
|
|
filetype to another. A given filetype can be mapped to use the linters
|
|
run for another given filetype.
|
|
|
|
This |Dictionary| will be merged with a default dictionary containing the
|
|
following values: >
|
|
|
|
{
|
|
\ 'zsh': 'sh',
|
|
\ 'csh': 'sh',
|
|
\}
|
|
<
|
|
For example, if you wish to map a new filetype `'foobar'` to run the `'php'`
|
|
linters, you could set the following: >
|
|
|
|
let g:ale_linter_aliases = {'foobar': 'php'}
|
|
<
|
|
When combined with the |g:ale_linters| option, the original filetype
|
|
(`'foobar'`) will be used for determining which linters to run,
|
|
not the aliased type (`'php'`). This allows an aliased type to run a
|
|
different set of linters from the type it is being mapped to.
|
|
|
|
Passing a list of filetypes is also supported. Say you want to lint
|
|
javascript and css embedded in HTML (using linters that support that).
|
|
You could alias `html` like so:
|
|
|
|
`let g:ale_linter_aliases = {'html': ['html', 'javascript', 'css']}`
|
|
|
|
Note that `html` itself was included as an alias. That is because aliases
|
|
will override the original linters for the aliased filetepe.
|
|
|
|
Linter aliases can be configured in each buffer with buffer-local variables.
|
|
ALE will first look for aliases for filetypes in the `b:ale_linter_aliases`
|
|
variable, then `g:ale_linter_aliases`, and then a default Dictionary.
|
|
|
|
|
|
g:ale_linters *g:ale_linters*
|
|
*b:ale_linters*
|
|
Type: |Dictionary|
|
|
Default: `{}`
|
|
|
|
The |g:ale_linters| option sets a |Dictionary| mapping a filetype
|
|
to a |List| of linter programs to be run when checking particular filetypes.
|
|
Only the filetypes specified in the dictionary will be limited in terms
|
|
of which linters will be run.
|
|
|
|
This |Dictionary| will be merged with a default dictionary containing the
|
|
following values: >
|
|
|
|
{
|
|
\ 'csh': ['shell'],
|
|
\ 'rust': ['cargo'],
|
|
\ 'text': [],
|
|
\ 'zsh': ['shell'],
|
|
\}
|
|
<
|
|
This option can be used to enable only a particular set of linters for a
|
|
file. For example, you can enable only 'eslint' for JavaScript files: >
|
|
|
|
let g:ale_linters = {'javascript': ['eslint']}
|
|
<
|
|
If you want to disable all linters for a particular filetype, you can pass
|
|
an empty list of linters as the value: >
|
|
|
|
let g:ale_linters = {'javascript': []}
|
|
<
|
|
All linters available for a given filetype can be enabled by using the
|
|
string `'all'`: >
|
|
|
|
let g:ale_linters = {'c': 'all'}
|
|
<
|
|
Linters can be configured in each buffer with buffer-local variables. ALE
|
|
will first look for linters for filetypes in the `b:ale_linters` variable,
|
|
then `g:ale_linters`, and then a default Dictionary.
|
|
|
|
|
|
g:ale_max_buffer_history_size *g:ale_max_buffer_history_size*
|
|
|
|
Type: |Number|
|
|
Default: `20`
|
|
|
|
This setting controls the maximum number of commands which will be stored in
|
|
the command history used for |ALEInfo|. Command history will be rotated in
|
|
a FIFO manner. If set to a number <= 0, then the history will be
|
|
continuously set to an empty |List|.
|
|
|
|
History can be disabled completely with |g:ale_history_enabled|.
|
|
|
|
|
|
g:ale_open_list *g:ale_open_list*
|
|
|
|
Type: |Number|
|
|
Default: `0`
|
|
|
|
When set to `1`, this will cause ALE to automatically open a window for
|
|
the loclist (|lopen|) or for the quickfix list instead if
|
|
|g:ale_set_quickfix| is `1`. (|copen|)
|
|
|
|
The window will be kept open until all warnings or errors are cleared,
|
|
including those not set by ALE, unless |g:ale_keep_list_window_open| is set
|
|
to `1`, in which case the window will be kept open until closed manually.
|
|
|
|
|
|
g:ale_set_highlights *g:ale_set_highlights*
|
|
|
|
Type: |Number|
|
|
Default: `has('syntax')`
|
|
|
|
When this option is set to `1`, highlights will be set in for erros and
|
|
warnings. The `ALEError` and `ALEWarning` highlight groups will be used to
|
|
provide highlights, and default to linking to `SpellBad` and `SpellCap`
|
|
respectively by default.
|
|
|
|
|
|
g:ale_set_loclist *g:ale_set_loclist*
|
|
|
|
Type: |Number|
|
|
Default: `1`
|
|
|
|
When this option is set to `1`, the |loclist| will be populated with any
|
|
warnings and errors which are found by ALE. This feature can be used to
|
|
implement jumping between errors through typical use of |lnext| and |lprev|.
|
|
|
|
|
|
g:ale_set_quickfix *g:ale_set_quickfix*
|
|
|
|
Type: |Number|
|
|
Default: `0`
|
|
|
|
When this option is set to `1`, the |quickfix| list will be populated with any
|
|
warnings and errors which are found by ALE, instead of the |loclist|. The
|
|
loclist will never be populated when this option is on.
|
|
|
|
|
|
g:ale_set_signs *g:ale_set_signs*
|
|
|
|
Type: |Number|
|
|
Default: `has('signs')`
|
|
|
|
When this option is set to `1`, the |sign| column will be populated with
|
|
signs marking where errors and warnings appear in the file. The
|
|
`ALEErrorSign` and `ALEWarningSign` highlight groups will be used to provide
|
|
highlighting for the signs. The text used for signs can be customised with
|
|
the |g:ale_sign_error| and |g:ale_sign_warning| options. The `ALEErrorSign`
|
|
and `ALEWarningLine` highlight groups will be used to provide highlighting
|
|
for the lines that the signs reside on.
|
|
|
|
|
|
g:ale_sign_column_always *g:ale_sign_column_always*
|
|
|
|
Type: |Number|
|
|
Default: `0`
|
|
|
|
By default, the sign gutter will disappear when all warnings and errors have
|
|
been fixed for a file. When this option is set to `1`, the sign column will
|
|
remain open. This can be preferable if you don't want the text in your file
|
|
to move around as you edit a file.
|
|
|
|
|
|
g:ale_sign_error *g:ale_sign_error*
|
|
|
|
Type: |String|
|
|
Default: `'>>'`
|
|
|
|
This string can be changed to change the characters used for the sign gutter
|
|
for lines which at least one error on them. Lines with both errors and
|
|
warnings on them will show the error marker, as errors take precedence.
|
|
|
|
|
|
g:ale_sign_offset *g:ale_sign_offset*
|
|
|
|
Type: |Number|
|
|
Default: `1000000`
|
|
|
|
This variable controls offset from which numeric IDs will be generated for
|
|
new signs. Signs cannot share the same ID values, so when two Vim plugins
|
|
set signs at the same time, the IDs have to be configured such that they do
|
|
not conflict with one another. If the IDs used by ALE are found to conflict
|
|
with some other plugin, this offset value can be changed, and hopefully both
|
|
plugins will work together. See |sign-place| for more information on how
|
|
signs are set.
|
|
|
|
|
|
g:ale_sign_warning *g:ale_sign_warning*
|
|
|
|
Type: |String|
|
|
Default: `'--'`
|
|
|
|
This string can be changed to change the characters used for the sign gutter
|
|
for lines which at least one warning on them.
|
|
|
|
|
|
g:ale_statusline_format *g:ale_statusline_format*
|
|
|
|
Type: |List|
|
|
Default: `['%d error(s)', '%d warning(s)', 'OK']`
|
|
|
|
This variable defines the format of |`ale#statusline#status()`| output.
|
|
- The 1st element is for errors
|
|
- The 2nd element is for warnings
|
|
- The 3rd element is for when no errors are detected
|
|
|
|
|
|
g:ale_warn_about_trailing_whitespace *g:ale_warn_about_trailing_whitespace*
|
|
b:ale_warn_about_trailing_whitespace *b:ale_warn_about_trailing_whitespace*
|
|
|
|
Type: |Number|
|
|
Default: `1`
|
|
|
|
When this option is set to `1`, warnings relating to trailing whitespace on
|
|
lines will be shown in signs, the loclist, and echo messages, etc. If these
|
|
errors are found to be too irritating while edits are being made, and you
|
|
have configured Vim to automatically remove trailing whitespace, then you
|
|
can disable these warnings for some linters by setting this option to `0`.
|
|
|
|
Not all linters may respect this option. If a linter does not, please file a
|
|
bug report, and it may be possible to add such support.
|
|
|
|
This option may be configured on a per buffer basis.
|
|
|
|
|
|
===============================================================================
|
|
4. Linter Options and Recommendations *ale-linter-options*
|
|
|
|
Linter options are documented in individual help files. See the table of
|
|
contents at |ale-contents|.
|
|
|
|
Every linter variable can be set globally, or individually for each buffer.
|
|
For example, `b:ale_python_flake8_executable` will override any values
|
|
set for `g:ale_python_flake8_executable`.
|
|
|
|
|
|
===============================================================================
|
|
5. Commands/Keybinds *ale-commands*
|
|
|
|
ALELint *ALELint*
|
|
|
|
Run ALE once for the current buffer. This command can be used to run ALE
|
|
manually, instead of automatically, if desired.
|
|
|
|
This command will also run linters where `lint_file` is set to `1`, or in
|
|
other words linters which check the file instead of the Vim buffer.
|
|
|
|
A plug mapping `<Plug>(ale_lint)` is defined for this command.
|
|
|
|
|
|
ALEPrevious *ALEPrevious*
|
|
ALEPreviousWrap *ALEPreviousWrap*
|
|
ALENext *ALENext*
|
|
ALENextWrap *ALENextWrap*
|
|
*ale-navigation-commands*
|
|
|
|
Move between warnings or errors in a buffer. ALE will only navigate between
|
|
the errors or warnings it generated, even if both |g:ale_set_quickfix|
|
|
and |g:ale_set_loclist| are set to `0`.
|
|
|
|
`ALEPrevious` and `ALENext` will stop at the top and bottom of a file, while
|
|
`ALEPreviousWrap` and `ALENextWrap` will wrap around the file to find
|
|
the last or first warning or error in the file, respectively.
|
|
|
|
The following |<Plug>| mappings are defined for the commands: >
|
|
<Plug>(ale_previous) - ALEPrevious
|
|
<Plug>(ale_previous_wrap) - ALEPreviousWrap
|
|
<Plug>(ale_next) - ALENext
|
|
<Plug>(ale_next_wrap) - ALENextWrap
|
|
<
|
|
For example, these commands could be bound to the keys Ctrl + j
|
|
and Ctrl + k: >
|
|
|
|
" Map movement through errors without wrapping.
|
|
nmap <silent> <C-k> <Plug>(ale_previous)
|
|
nmap <silent> <C-j> <Plug>(ale_next)
|
|
" OR map keys to use wrapping.
|
|
nmap <silent> <C-k> <Plug>(ale_previous_wrap)
|
|
nmap <silent> <C-j> <Plug>(ale_next_wrap)
|
|
<
|
|
|
|
ALEToggle *ALEToggle*
|
|
ALEEnable *ALEEnable*
|
|
ALEDisable *ALEDisable*
|
|
|
|
Enable or disable ALE, including all of its autocmd events, loclist items,
|
|
quickfix items, signs, current jobs, etc. Calling this option will change
|
|
the |g:ale_enabled| variable.
|
|
|
|
|
|
ALEDetail *ALEDetail*
|
|
|
|
Show the full linter message for the current line. This will only have an
|
|
effect on lines that contain a linter message.
|
|
|
|
A plug mapping `<Plug>(ale_detail)` is defined for this command.
|
|
|
|
===============================================================================
|
|
6. API *ale-api*
|
|
|
|
ale#Queue(delay, [linting_flag]) *ale#Queue()*
|
|
|
|
Run linters for the current buffer, based on the filetype of the buffer,
|
|
with a given `delay`. A `delay` of `0` will run the linters immediately.
|
|
The linters will always be run in the background. Calling this function
|
|
again from the same buffer
|
|
|
|
An optional `linting_flag` argument can be given. If `linting_flag`
|
|
is `'lint_file'`, then linters where the `lint_file` option is set to `1` will be
|
|
run. Linters with `lint_file` set to `1` are not run by default.
|
|
|
|
|
|
ale#engine#CreateDirectory(buffer) *ale#engine#CreateDirectory()*
|
|
|
|
Create a new temporary directory with a unique name, and manage that
|
|
directory with |ale#engine#ManageDirectory()|, so it will be removed as
|
|
soon as possible.
|
|
|
|
It is advised to only call this function from a callback function for
|
|
returning a linter command to run.
|
|
|
|
|
|
ale#engine#EscapeCommandPart(command_part) *ale#engine#EscapeCommandPart()*
|
|
|
|
Given a |String|, return a |String| with all `%` characters replaced with
|
|
`%%` instead. This function can be used to escape strings which are
|
|
dynamically generated for commands before handing them over to ALE,
|
|
so that ALE doesn't treat any strings with `%` formatting sequences
|
|
specially.
|
|
|
|
|
|
ale#engine#GetLoclist(buffer) *ale#engine#GetLoclist()*
|
|
|
|
Given a buffer number, this function will rerurn the list of warnings and
|
|
errors reported by ALE for a given buffer in the format accepted by
|
|
|setqflist()|.
|
|
|
|
|
|
ale#engine#ManageFile(buffer, filename) *ale#engine#ManageFile()*
|
|
|
|
Given a buffer number for a buffer currently running some linting tasks
|
|
and a filename, register a filename with ALE for automatic deletion after
|
|
linting is complete, or when Vim exits.
|
|
|
|
If Vim exits suddenly, ALE will try its best to remove temporary files, but
|
|
ALE cannot guarantee with absolute certainty that the files will be removed.
|
|
It is advised to create temporary files in the operating system's managed
|
|
temporary file directory, such as with |tempname()|.
|
|
|
|
Directory names should not be given to this function. ALE will only delete
|
|
files and symlinks given to this function. This is to prevent entire
|
|
directories from being accidentally deleted, say in cases of writing
|
|
`dir . '/' . filename` where `filename` is actually `''`, etc. ALE instead
|
|
manages directories separetly with the |ale#engine#ManageDirectory| function.
|
|
|
|
|
|
ale#engine#ManageDirectory(buffer, directory) *ale#engine#ManageDirectory()*
|
|
|
|
Like |ale#engine#ManageFile()|, but directories and all of their contents
|
|
will be deleted, akin to `rm -rf directory`, which could lead to loss of
|
|
data if mistakes are made. This command will also delete any temporary
|
|
filenames given to it.
|
|
|
|
It is advised to use |ale#engine#ManageFile()| instead for deleting single
|
|
files.
|
|
|
|
|
|
ale#linter#Define(filetype, linter) *ale#linter#Define()*
|
|
|
|
Given a |String| for a filetype and a |Dictionary| Describing a linter
|
|
configuration, add a linter for the given filetype. The dictionaries each
|
|
offer the following options:
|
|
|
|
`name` The name of the linter. These names will be used by
|
|
|g:ale_linters| option for enabling/disabling
|
|
particular linters.
|
|
|
|
This argument is required.
|
|
|
|
`callback` A |String| or |Funcref| for a callback function
|
|
accepting two arguments (buffer, lines), for a
|
|
buffer number the output is for, and the lines of
|
|
output from a linter.
|
|
|
|
This callback function should return a |List| of
|
|
|Dictionary| objects in the format accepted by
|
|
|setqflist()|. The |List| will be sorted by line and
|
|
then column order so it can be searched with a binary
|
|
search by in future before being passed on to the
|
|
|loclist|, etc.
|
|
|
|
This argument is required.
|
|
|
|
The keys for each item in the List will be handled in
|
|
the following manner:
|
|
|
|
`text` - This error message is required.
|
|
`lnum` - The line number is required. Any strings
|
|
will be automatically converted to numbers by
|
|
using `str2nr()`.
|
|
|
|
Line 0 will be moved to line 1, and lines beyond
|
|
the end of the file will be moved to the end.
|
|
`col` - The column number is optional and will
|
|
default to `0`. Any strings will be automatically
|
|
coverted to number using `str2nr()`.
|
|
`bufnr` - The buffer number should match the buffer
|
|
being checked, and this value will default to
|
|
the buffer being checked.
|
|
`vcol` - Defaults to `0`.
|
|
`type` - Defaults to `'E'`.
|
|
`nr` - Defaults to `-1`.
|
|
|
|
`executable` A |String| naming the executable itself which
|
|
will be run. This value will be used to check if the
|
|
program requested is installed or not.
|
|
|
|
Either this or the `executable_callback` argument
|
|
must be provided.
|
|
|
|
`executable_callback ` A |String| or |Funcref| for a callback function
|
|
accepting a buffer number. A |String| should be
|
|
returned for the executable to check. This can be
|
|
used in place of `executable` when more complicated
|
|
processing is needed.
|
|
|
|
`command` A |String| for an executable to run asynchronously.
|
|
This command will be fed the lines from the buffer to
|
|
check, and will produce the lines of output given to
|
|
the `callback`.
|
|
|
|
`command_callback` A |String| or |Funcref| for a callback function
|
|
accepting a buffer number. A |String| should be
|
|
returned for a command to run. This can be used in
|
|
place of `command` when more complicated processing
|
|
is needed.
|
|
|
|
If an empty string is returned from the callback,
|
|
no jobs for linting will be run for that linter.
|
|
This can be used for skipping a linter call,
|
|
say if no configuration file was found.
|
|
|
|
*ale-command-chain*
|
|
`command_chain` A |List| of |Dictionary| items defining a series
|
|
of commands to be run. At least one |Dictionary|
|
|
should be provided. Each Dictionary must contain the
|
|
key `callback`, defining a |String| or |Funcref| for
|
|
a function returning a |String| for a command to run.
|
|
|
|
The callback functions for each command after the
|
|
first command in in the chain should accept two
|
|
arguments `(buffer, output)`, a buffer number and a
|
|
|List| of lines of output from the previous command
|
|
in the chain.
|
|
|
|
The first callback function in a chain accepts only
|
|
a `(buffer)` argument, as there are no previous
|
|
commands to run which return `output`.
|
|
|
|
If an empty string is returned for a command in a
|
|
chain, that command in the chain will be skipped,
|
|
and the next function in the chain will be called
|
|
immediately instead. If the last command in a chain
|
|
returns an empty string, then no linting will be
|
|
performed.
|
|
|
|
Commands in the chain will all use the
|
|
`output_stream` value provided in the root
|
|
|Dictionary|. Each command in the chain can also
|
|
provide an `output_stream` key to override this value.
|
|
See the `output_stream` description for more
|
|
information.
|
|
|
|
Commands in the chain all behave as if `read_buffer`
|
|
is set to `0` by default, except for the last command
|
|
in the chain, which uses the value set for
|
|
`read_buffer` in the root |Dictionary|. Each command
|
|
in the chain can also provide a `read_buffer` key
|
|
to override these values.
|
|
See the `read_buffer` description for more
|
|
information.
|
|
|
|
`output_stream` A |String| for the output stream the lines of output
|
|
should be read from for the command which is run. The
|
|
accepted values are `'stdout'`, `'stderr'`, and
|
|
`'both'`. This argument defaults to `'stdout'`. This
|
|
argument can be set for linter programs which output
|
|
their errors and warnings to the stderr stream
|
|
instead of stdout. The option `'both'` will read
|
|
from both stder and stdout at the same time.
|
|
|
|
`read_buffer` A |Number| (`0` or `1`) indicating whether a command
|
|
should read the Vim buffer as input via stdin. This
|
|
option is set to `1` by default, and can be disabled
|
|
if a command manually reads from a temporary file
|
|
instead, etc.
|
|
|
|
*ale-lint-file*
|
|
`lint_file` A |Number| (`0` or `1`) indicating whether a command
|
|
should read the file instead of the Vim buffer. This
|
|
option can be used for linters which must check the
|
|
file on disk, and which cannot check a Vim buffer
|
|
instead.
|
|
|
|
Linters set with this option will not be run as a
|
|
user types, per |g:ale_lint_on_text_changed|. Linters
|
|
will instead be run only when events occur against
|
|
the file on disk, including |g:ale_lint_on_enter|
|
|
and |g:ale_lint_on_save|. Linters with this option
|
|
set to `1` will also be run when linters are run
|
|
manually, per |ALELint-autocmd|.
|
|
|
|
When this option is set to `1`, `read_buffer` will
|
|
be set automatically to `0`. The two options cannot
|
|
be used together.
|
|
|
|
Only one of `command`, `command_callback`, or `command_chain` should be
|
|
specified. `command_callback` is generally recommended when a command string
|
|
needs to be generated dynamically, or any global options are used.
|
|
`command_chain` is recommended where any system calls need to be made to
|
|
retrieve some kind of information before running the final command.
|
|
|
|
If temporary files or directories are created for commands run with
|
|
`command_callback` or `command_chain`, then these tempoary files or
|
|
directories can be managed by ALE, for automatic deletion.
|
|
See |ale#engine#ManageFile()| and |ale#engine#ManageDirectory| for more
|
|
information.
|
|
|
|
*ale-command-format-strings*
|
|
|
|
All command strings will be formatted for special character sequences.
|
|
Any substring `%s` will be replaced with the full path to the current file
|
|
being edited. This format option can be used to pass the exact filename
|
|
being edited to a program.
|
|
|
|
For example: >
|
|
'command': 'eslint -f unix --stdin --stdin-filename %s'
|
|
<
|
|
Any substring `%t` will be replaced with a path to a temporary file. Merely
|
|
adding `%t` will cause ALE to create a temporary file containing the
|
|
contents of the buffer being checked. All occurrences of `%t` in command
|
|
strings will reference the one temporary file. The temporary file will be
|
|
created inside a temporary directory, and the entire temporary directory
|
|
will be automatically deleted, following the behaviour of
|
|
|ale#engine#ManageDirectory|. This option can be used for some linters which
|
|
do not support reading from stdin.
|
|
|
|
For example: >
|
|
'command': 'ghc -fno-code -v0 %t',
|
|
<
|
|
The character sequence `%%` can be used to emit a literal `%` into a
|
|
command, so literal character sequences `%s` and `%t` can be escaped by
|
|
using `%%s` and `%%t` instead, etc.
|
|
|
|
If a callback for a command generates part of a command string which might
|
|
possibly contain `%%`, `%s`, or `%t` where the special formatting behaviour
|
|
is not desired, the |ale#engine#EscapeCommandPart()| function can be used to
|
|
replace those characters to avoid formatting issues.
|
|
|
|
*ale-linter-loading-behaviour*
|
|
|
|
Linters for ALE will be loaded by searching |runtimepath| in the following
|
|
format: >
|
|
|
|
ale_linters/<filetype>/<linter_name>.vim
|
|
<
|
|
Any linters which exist anywhere in |runtimepath| with that directory
|
|
structure will be automatically loaded for the matching |filetype|. Filetypes
|
|
containing `.` characters will be split into individual parts, and files
|
|
will be loaded for each filetype between the `.` characters.
|
|
|
|
|
|
ale#linter#Get(filetype) *ale#linter#Get()*
|
|
|
|
Return all of linters configured for a given filetype as a |List| of
|
|
|Dictionary| values in the format specified by |ale#linter#Define()|.
|
|
|
|
Filetypes may be dot-seperated to invoke linters for multiple filetypes:
|
|
for instance, the filetype `javascript.jsx` will return linters for both the
|
|
`javascript` and `jsx` filetype.
|
|
|
|
Aliases may be defined in as described in |g:ale_linter_aliases|. Aliases
|
|
are applied after dot-seperated filetypes are broken up into their
|
|
components.
|
|
|
|
|
|
ale#statusline#Status() *ale#statusline#Status()*
|
|
|
|
Return a formatted string that can be added to the statusline.
|
|
The output's format is defined in |`g:ale_statusline_format`|.
|
|
To enable it, the following should be present in your |statusline| settings: >
|
|
%{ale#statusline#Status()}
|
|
|
|
|
|
ALELint *ALELint-autocmd*
|
|
|
|
This |User| autocommand is triggered by ALE every time it completes a lint
|
|
cycle. It can be used to update statuslines, send notifications, or
|
|
complete any other operation that needs to be done after linting has been
|
|
performed.
|
|
|
|
For example, you can echo a message when linting is complete like so:
|
|
>
|
|
autocmd User ALELint echom "ALE run!"
|
|
<
|
|
|
|
===============================================================================
|
|
7. Special Thanks *ale-special-thanks*
|
|
|
|
Special thanks to Mark Grealish (https://www.bhalash.com/) for providing ALE's
|
|
snazzy looking ale glass logo. Cheers, Mark!
|
|
|
|
===============================================================================
|
|
8. Contact *ale-contact*
|
|
|
|
If you like this plugin, and wish to get in touch, check out the GitHub
|
|
page for issues and more at https://github.com/w0rp/ale
|
|
|
|
If you wish to contact the author of this plugin directly, please feel
|
|
free to send an email to devw0rp@gmail.com.
|
|
|
|
|
|
Please drink responsibly, or not at all, which is ironically the preference
|
|
of w0rp, who is teetotal.
|
|
|
|
|
|
|
|
vim:tw=78:ts=2:sts=2:sw=2:ft=help:norl:
|