581 lines
23 KiB
Plaintext
581 lines
23 KiB
Plaintext
*ale.txt* For Vim version 8.0. Last change: 2016 October 10
|
|
*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 Specific Options....................|ale-linter-options|
|
|
4.1. eslint................................|ale-linter-options-eslint|
|
|
4.2. jshint................................|ale-linter-options-jshint|
|
|
4.3. phpcs.................................|ale-linter-options-phpcs|
|
|
4.4. html-tidy.............................|ale-linter-options-html-tidy|
|
|
4.5. c-gcc.................................|ale-linter-options-c-gcc|
|
|
4.6. cpp-gcc...............................|ale-linter-options-cpp-gcc|
|
|
4.7. fortran-gcc...........................|ale-linter-options-fortran-gcc|
|
|
4.8. shell.................................|ale-linter-options-shell|
|
|
4.9. shellcheck............................|ale-linter-options-shellcheck|
|
|
4.10. vint..................................|ale-linter-options-vint|
|
|
5. API........................................|ale-api|
|
|
6. Special Thanks.............................|ale-special-thanks|
|
|
7. 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.
|
|
|
|
* Bash: 'shell' (-n flag), 'shellcheck'
|
|
* Bourne Shell: 'shell' (-n flag), 'shellcheck'
|
|
* C: 'gcc'
|
|
* C++ (filetype cpp): 'gcc'
|
|
* CoffeeScript: 'coffee', 'coffelint'
|
|
* CSS: 'csslint'
|
|
* Cython (pyrex filetype): 'cython'
|
|
* D: 'dmd'
|
|
* Fortran: 'gcc'
|
|
* Go: 'gofmt -e', 'go vet', 'golint'
|
|
* Haskell: 'ghc'
|
|
* HTML: 'HTMLHint', 'tidy'
|
|
* JavaScript: 'eslint', 'jscs', 'jshint'
|
|
* JSON: 'jsonlint'
|
|
* Perl: 'perl' (-c flag), 'perlcritic'
|
|
* PHP: 'php' (-l flag), 'phpcs'
|
|
* Pug: 'pug-lint'
|
|
* Python: 'flake8'
|
|
* Ruby: 'rubocop'
|
|
* SASS: 'sasslint'
|
|
* SCSS: 'sasslint', 'scsslint'
|
|
* Scala: 'scalac'
|
|
* TypeScript: 'tslint'
|
|
* Verilog: 'iverilog', 'verilator'
|
|
* Vim: 'vint'
|
|
* YAML: 'yamllint'
|
|
|
|
===============================================================================
|
|
3. Global Options *ale-options*
|
|
|
|
g:ale_linters *g:ale_linters*
|
|
|
|
Type: |Dictionary|
|
|
Default: unset
|
|
|
|
The |g:ale_linters| option sets a |Dictionary| mapping a filetype
|
|
to a |List| of linter programs to be run when checking particular filetypes.
|
|
By default, this dictionary will not be set at all, and all possible
|
|
linter programs will be run for a given filetype, if the linter programs
|
|
are found to be |executable|.
|
|
|
|
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': []}
|
|
<
|
|
|
|
g:ale_buffer_loclist_map *g:ale_buffer_loclist_map*
|
|
|
|
Type: |Dictionary|
|
|
Default: `{}`
|
|
|
|
This variable is used internally by ALE for tracking the warnings and
|
|
errors for a particular buffer. The dictionary maps a buffer number to
|
|
a |List| of |Dictionary| items in the format accepted by |setqflist()|,
|
|
with a minor addition of a `linter_name` for each object which describes
|
|
the linter which reported the warnings and errors. (A buffer may run
|
|
multiple linters in combination on the same filetype.)
|
|
|
|
NOTE: This variable should not be modified outside of the plugin itself,
|
|
but can be read in other plugins whenever information about the current
|
|
errors and warnings ALE is reporting is needed.
|
|
|
|
|
|
g:ale_lint_on_text_changed *g:ale_lint_on_text_changed*
|
|
|
|
Type: |Number|
|
|
Default: `1`
|
|
|
|
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 0. 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.
|
|
|
|
|
|
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 `1`.
|
|
|
|
|
|
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_save *g:ale_lint_on_save*
|
|
|
|
Type: |Number|
|
|
Default: `0`
|
|
|
|
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_set_loclist *g:ale_set_loclist*
|
|
|
|
Type: |Number|
|
|
Default: `1`
|
|
|
|
When this option is set to `1`, the |loclist| will be populate 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_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.
|
|
|
|
|
|
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_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_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_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_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_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_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_warn_about_trailing_whitespace *g: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.
|
|
|
|
|
|
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: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: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|.
|
|
|
|
===============================================================================
|
|
4. Linter Specific Options *ale-linter-options*
|
|
|
|
Some linters have specific options which can be configured for each of them,
|
|
for customising their behaviour.
|
|
|
|
-------------------------------------------------------------------------------
|
|
4.1. eslint *ale-linter-options-eslint*
|
|
|
|
g:ale_javascript_eslint_executable *g:ale_javascript_eslint_executable*
|
|
|
|
Type: |String|
|
|
Default: `'eslint'`
|
|
|
|
This variable can be changed to change the path to eslint. If you have
|
|
eslint_d installed, you can set this option to use eslint_d instead.
|
|
|
|
|
|
-------------------------------------------------------------------------------
|
|
4.2. jshint *ale-linter-options-jshint*
|
|
|
|
g:ale_javascript_jshint_executable *g:ale_javascript_jshint_executable*
|
|
|
|
Type: |String|
|
|
Default: `'jshint'`
|
|
|
|
This variable can be changed to change the path to jshint.
|
|
|
|
|
|
-------------------------------------------------------------------------------
|
|
4.3. phpcs *ale-linter-options-phpcs*
|
|
|
|
g:ale_php_phpcs_standard *g:ale_php_phpcs_standard*
|
|
|
|
Type: |String|
|
|
Default: `''`
|
|
|
|
This variable can be set to specify the coding standard used by phpcs. If no
|
|
coding standard is specified, phpcs will default to checking against the
|
|
PEAR coding standard, or the standard you have set as the default.
|
|
|
|
|
|
-------------------------------------------------------------------------------
|
|
4.4. html-tidy *ale-linter-options-html-tidy*
|
|
|
|
g:ale_html_tidy_executable *g:ale_html_tidy_executable*
|
|
|
|
Type: |String|
|
|
Default: `'tidy'`
|
|
|
|
This variable can be changed to change the path to tidy.
|
|
|
|
|
|
g:ale_html_tidy_args *g:ale_html_tidy_args*
|
|
|
|
Type: |String|
|
|
Default: `'-q -e -language en'`
|
|
|
|
This variable can be changed to change the arguments provided to the
|
|
executable.
|
|
|
|
ALE will attempt to automatically detect the appropriate file encoding to
|
|
provide to html-tidy, and fall back to UTF-8 when encoding detection fails.
|
|
|
|
The recognized file encodings are as follows: ascii, big5, cp1252 (win1252),
|
|
cp850 (ibm858), cp932 (shiftjis), iso-2022-jp (iso-2022), latin1, macroman
|
|
(mac), sjis (shiftjis), utf-16le, utf-16, utf-8
|
|
|
|
|
|
-------------------------------------------------------------------------------
|
|
4.5. c-gcc *ale-linter-options-c-gcc*
|
|
|
|
g:ale_c_gcc_options *g:ale_c_gcc_options*
|
|
|
|
Type: |String|
|
|
Default: `'-Wall'`
|
|
|
|
This variable can be change to modify flags given to gcc.
|
|
|
|
|
|
-------------------------------------------------------------------------------
|
|
4.6. cpp-gcc *ale-linter-options-cpp-gcc*
|
|
|
|
g:ale_cpp_gcc_options *g:ale_cpp_gcc_options*
|
|
|
|
Type: |String|
|
|
Default: `'-Wall'`
|
|
|
|
This variable can be changed to modify flags given to gcc.
|
|
|
|
|
|
-------------------------------------------------------------------------------
|
|
4.7. fortran-gcc *ale-linter-options-fortran-gcc*
|
|
|
|
g:ale_fortran_gcc_options *g:ale_fortran_gcc_options*
|
|
|
|
Type: |String|
|
|
Default: `'-Wall'`
|
|
|
|
This variable can be changed to modify flags given to gcc.
|
|
|
|
|
|
-------------------------------------------------------------------------------
|
|
4.8. shell *ale-linter-options-shell*
|
|
|
|
g:ale_linters_sh_shell_default_shell *g:ale_linters_sh_shell_default_shell*
|
|
|
|
Type: |String|
|
|
Default: The current shell (`$SHELL`) or `'bash'` if that cannot be read.
|
|
|
|
When ALE runs the linter for shells with the `-n` flag, it will attempt to
|
|
read the shell from the shebang (`#!`) line from the shell script to
|
|
determine the shell program to run. When this detection fails, this variable
|
|
will be used instead.
|
|
|
|
|
|
-------------------------------------------------------------------------------
|
|
4.9. shellcheck *ale-linter-options-shellcheck*
|
|
|
|
g:ale_linters_sh_shellckeck_exclusions *g:ale_linters_sh_shellckeck_exclusions*
|
|
|
|
Type: |String|
|
|
Default: `''`
|
|
|
|
Set this variable to exclude test(s) for shellcheck (-e/--exclude option).
|
|
|
|
|
|
-------------------------------------------------------------------------------
|
|
4.10. vint *ale-linter-options-vint*
|
|
|
|
g:ale_vim_vint_show_style_issues *g:ale_vim_vint_show_style_issues*
|
|
|
|
Type: |Number|
|
|
Default: `1`
|
|
|
|
This variable will enable/disable style issues for Vint. When this option
|
|
is disabled, only warnings and errors which are not purely style issues
|
|
will be reported.
|
|
|
|
|
|
===============================================================================
|
|
5. API *ale-api*
|
|
|
|
ale#Queue(delay) *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
|
|
|
|
|
|
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.
|
|
|
|
`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`.
|
|
|
|
Either this or the `command_callback` argument must
|
|
be provided.
|
|
|
|
`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.
|
|
|
|
`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.
|
|
|
|
Some programs for checking for errors are not capable of receiving input
|
|
from stdin, as is required by ALE. To remedy this, a wrapper script is
|
|
provided named in the variable |g:ale#util#stdin_wrapper|. This variable
|
|
can be called with the regular arguments for any command to forward data
|
|
from stdin to the program, by way of creating a temporary file. The first
|
|
argument to the stdin wrapper must be a file extension to save the temporary
|
|
file with, and the following arguments are the command as normal.
|
|
For example: >
|
|
'command': g:ale#util#stdin_wrapper . ' .hs ghc -fno-code -v0',
|
|
<
|
|
|
|
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()|.
|
|
|
|
|
|
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()}
|
|
|
|
|
|
g:ale#util#stdin_wrapper *g:ale#util#stdin_wrapper*
|
|
This variable names a wrapper script for sending stdin input to programs
|
|
which cannot accept input via stdin. See |ale#linter#Define()| for more.
|
|
|
|
===============================================================================
|
|
6. 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!
|
|
|
|
===============================================================================
|
|
7. 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:
|