summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorw0rp <devw0rp@gmail.com>2016-10-06 00:22:32 +0100
committerw0rp <devw0rp@gmail.com>2016-10-06 00:22:32 +0100
commit192bf17e9268824c948a5b9c5bb61c7520ea47d8 (patch)
treeb3e34e7c0a807455db33bdedb87b1681488672f9 /doc
parentf0da729a9d3dba85bfb09ccbf193fb1791bec696 (diff)
downloadale-192bf17e9268824c948a5b9c5bb61c7520ea47d8.zip
Add a help file for the project.
Diffstat (limited to 'doc')
-rw-r--r--doc/ale.txt322
1 files changed, 322 insertions, 0 deletions
diff --git a/doc/ale.txt b/doc/ale.txt
new file mode 100644
index 00000000..e32df32e
--- /dev/null
+++ b/doc/ale.txt
@@ -0,0 +1,322 @@
+*ale.txt* For Vim version 8.0. Last change: 2016 October 5
+*ale*
+
+ALE - Asychronous Lint Engine
+
+===============================================================================
+CONTENTS *ale-contents*
+
+ 1. Introduction...........................................|ale-introduction|
+ 2. Supported Languages & Tools............................|ale-support|
+ 3. Global Options.........................................|ale-options|
+ 4. API....................................................|ale-api|
+ 5. 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'
+* CoffeeScript: 'coffelint'
+* CSS: 'csslint'
+* D: 'dmd'
+* Fortran: 'gcc'
+* Haskell: 'ghc'
+* HTML: 'tidy'
+* JavaScript: 'eslint', 'jscs', 'jshint'
+* JSON: 'jsonlint'
+* PHP: 'php' (-l flag)
+* Python: 'flake8'
+* Ruby: 'rubocop'
+* SASS: 'sasslint'
+* SCSS: 'sasslint', 'scsslint'
+* TypeScript: 'tslint'
+* 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_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| event 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.
+
+
+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.
+
+===============================================================================
+4. API *ale-api*
+
+ALELint(delay) *ALELint()*
+ 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
+
+ALEAddLinter(filetype, linter) *ALEAddLinter()*
+ 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'` and `'stderr'`. 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.
+
+ 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',
+<
+
+ALEGetLinters(filetype) *ALEGetLinters()*
+ Return all of linters configured for a given filetype as a |List| of
+ |Dictionary| values in the format specified by |ALEAddLinter()|.
+
+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 |ALEAddLinter| for more.
+
+===============================================================================
+5. 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: