From 74d879952cfa3a27b21869bdbfef909c793178bb Mon Sep 17 00:00:00 2001 From: w0rp Date: Sat, 20 May 2017 19:01:12 +0100 Subject: [PATCH] Document ALEFix --- README.md | 6 +++ doc/ale.txt | 105 ++++++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 100 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index cc9671b..06b3cdd 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,9 @@ back to a filesystem. In other words, this plugin allows you to lint while you type. +ALE also supports fixing problems with files by running commands in the +background with a command `ALEFix`. + ## Table of Contents 1. [Supported Languages and Tools](#supported-languages) @@ -138,6 +141,9 @@ 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. +ALE can fix files with the `ALEFix` command. Functions need to be configured +for different filetypes with the `g:ale_fixers` variable. See `:help ale-fix`. + ## 3. Installation diff --git a/doc/ale.txt b/doc/ale.txt index 74368c9..f88fbbc 100644 --- a/doc/ale.txt +++ b/doc/ale.txt @@ -9,7 +9,8 @@ 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| + 4. Fixing Problems......................|ale-fix| + 5. Linter Options and Recommendations...|ale-linter-options| asm...................................|ale-asm-options| gcc.................................|ale-asm-gcc| c.....................................|ale-c-options| @@ -93,10 +94,10 @@ CONTENTS *ale-contents* xmllint.............................|ale-xml-xmllint| 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| + 6. Commands/Keybinds....................|ale-commands| + 7. API..................................|ale-api| + 8. Special Thanks.......................|ale-special-thanks| + 9. Contact..............................|ale-contact| =============================================================================== 1. Introduction *ale-introduction* @@ -107,7 +108,7 @@ 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: +ALE supports the following key features for linting: 1. Running linters when text is changed. 2. Running linters when files are opened. @@ -115,6 +116,10 @@ ALE supports the following key features: 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. +7. Setting syntax highlights for errors. + +ALE can fix problems with files with the |ALEFix| command, using the same job +control functionality used for checking for problems. =============================================================================== 2. Supported Languages & Tools *ale-support* @@ -266,6 +271,18 @@ g:ale_enabled *g:ale_enabled* the |ALEToggle| command, which changes this option. +g:ale_fixers *g:ale_fixers* + *b:ale_fixers* + + Type: |Dictionary| + Default: `{}` + + A mapping from filetypes to |List| values for functions for fixing errors. + See |ale-fix| for more information. + + This variable can be overriden with variables in each buffer. + + g:ale_history_enabled *g:ale_history_enabled* Type: |Number| @@ -604,7 +621,57 @@ b:ale_warn_about_trailing_whitespace *b:ale_warn_about_trailing_whitespace* =============================================================================== -4. Linter Options and Recommendations *ale-linter-options* +4. Fixing Problems *ale-fix* + +ALE can fix problems with files with the |ALEFix| command. When |ALEFix| is +run, the variable |g:ale_fixers| will be read for getting a |List| of commands +for filetypes, split on `.`, and the functions named in |g:ale_fixers| will be +executed for fixing the errors. + +The values for `g:ale_fixers` can be a list of |String|, |Funcref|, or +|lambda| values. String values must either name a function, or a short name +for a function set in the ALE fixer registry. + +Each function for fixing errors must accept two arguments `(buffer, lines)`, +representing the buffer being fixed and the lines to fix. The functions must +return either `0`, for changing nothing, a |List| for new lines to set, or a +|Dictionary| for describing a command to be run in the background. + +When a |Dictionary| is returned for an |ALEFix| callback, the following keys +are supported for running the commands. + + `command` A |String| for the command to run. This key is required. + + When `%t` is included in a command string, a temporary + file will be created, containing the lines from the file + after previous adjustment have been done. + + `read_temporary_file` When set to `1`, ALE will read the contents of the + temporary file created for `%t`. This option can be used + for commands which need to modify some file on disk in + order to fix files. + + *ale-fix-configuration* + +Synchronous functions and asynchronous jobs will be run in a sequence for +fixing files, and can be combined. For example: +> + let g:ale_fixers.javascript = [ + \ 'DoSomething', + \ 'eslint', + \ {buffer, lines -> filter(lines, 'v:val !=~ ''^\s*//''')}, + \] + + ALEFix +< +The above example will call a function called `DoSomething` which could act +upon some lines immediately, then run `eslint` from the ALE registry, and +then call a lambda function which will remove every single line comment +from the file. + + +=============================================================================== +5. Linter Options and Recommendations *ale-linter-options* Linter options are documented in individual help files. See the table of contents at |ale-contents|. @@ -615,7 +682,12 @@ set for `g:ale_python_flake8_executable`. =============================================================================== -5. Commands/Keybinds *ale-commands* +6. Commands/Keybinds *ale-commands* + +ALEFix *ALEFix* + + Fix problems with the current buffer. See |ale-fix| for more information. + ALELint *ALELint* @@ -676,7 +748,7 @@ ALEDetail *ALEDetail* A plug mapping `(ale_detail)` is defined for this command. =============================================================================== -6. API *ale-api* +7. API *ale-api* ale#Queue(delay, [linting_flag]) *ale#Queue()* @@ -745,6 +817,17 @@ ale#engine#ManageDirectory(buffer, directory) *ale#engine#ManageDirectory()* files. +ale#fix#registry#Add(name, func, filetypes, desc) *ale#fix#registry#Add()* + + Given a |String| `name` for a name to add to the registry, a |String| `func` + for a function name, a |List| `filetypes` for a list of filetypes to + set for suggestions, and a |String| `desc` for a short description of + the fixer, register a fixer in the registry. + + The `name` can then be used for |g:ale_fixers| in place of the function + name, and suggested for fixing files. + + ale#linter#Define(filetype, linter) *ale#linter#Define()* Given a |String| for a filetype and a |Dictionary| Describing a linter @@ -985,13 +1068,13 @@ ALELint *ALELint-autocmd* < =============================================================================== -7. Special Thanks *ale-special-thanks* +8. 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* +9. 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