Merge pull request #1203 from Carpetsmoker/autocmd-start

Add ALEStartLint autocmd

4 files changed, 40 insertions, 19 deletions

diff --git a/README.md b/README.md
index d2c4c5e1..6d390135 100644
--- a/README.md
+++ b/README.md
@@ -40,7 +40,7 @@ formatting tools, and some Language Server Protocol and `tsserver` features.
     5. [How can I show errors or warnings in my statusline?](#faq-statusline)
     6. [How can I show errors or warnings in my lightline?](#faq-lightline)
     7. [How can I change the format for echo messages?](#faq-echo-format)
-    8. [How can I execute some code when ALE stops linting?](#faq-autocmd)
+    8. [How can I execute some code when ALE starts or stops linting?](#faq-autocmd)
     9. [How can I navigate between errors quickly?](#faq-navigation)
     10. [How can I run linters only when I save files?](#faq-lint-on-save)
     11. [How can I use the quickfix list instead of the loclist?](#faq-quickfix)
@@ -493,16 +493,18 @@ Will give you:
 
 <a name="faq-autocmd"></a>
 
-### 5.viii. How can I execute some code when ALE stops linting?
+### 5.viii. How can I execute some code when ALE starts or stops linting?
 
 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.
+events whenever has a linter is started and has been successfully executed and
+processed. These events can be used to call arbitrary functions before and after
+ALE stops linting.
 
 ```vim
 augroup YourGroup
     autocmd!
-    autocmd User ALELint call YourFunction()
+    autocmd User ALELintPre  call YourFunction()
+    autocmd User ALELintPost call YourFunction()
 augroup END
 ```
 
diff --git a/autoload/ale/engine.vim b/autoload/ale/engine.vim
index 150b53c1..65e663aa 100644
--- a/autoload/ale/engine.vim
+++ b/autoload/ale/engine.vim
@@ -321,6 +321,8 @@ function! ale#engine#SetResults(buffer, loclist) abort
         call ale#engine#RemoveManagedFiles(a:buffer)
 
         " Call user autocommands. This allows users to hook into ALE's lint cycle.
+        silent doautocmd <nomodeline> User ALELintPost
+        " Old DEPRECATED name; call it for backwards compatibility.
         silent doautocmd <nomodeline> User ALELint
     endif
 endfunction
@@ -785,6 +787,8 @@ function! ale#engine#RunLinters(buffer, linters, should_lint_file) abort
     " We can only clear the results if we aren't checking the buffer.
     let l:can_clear_results = !ale#engine#IsCheckingBuffer(a:buffer)
 
+    silent doautocmd <nomodeline> User ALELintPre
+
     for l:linter in a:linters
         " Only run lint_file linters if we should.
         if !l:linter.lint_file || a:should_lint_file
diff --git a/doc/ale.txt b/doc/ale.txt
index fc4a984f..b818f871 100644
--- a/doc/ale.txt
+++ b/doc/ale.txt
@@ -2051,7 +2051,7 @@ ale#linter#Define(filetype, linter)                       *ale#linter#Define()*
                          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|.
+                         manually, per |ALELintPost-autocmd|.
 
                          When this option is set to `1`, `read_buffer` will
                          be set automatically to `0`. The two options cannot
@@ -2185,20 +2185,32 @@ ale#statusline#Count(buffer)                           *ale#statusline#Count()*
   `total`         -> The total number of problems.
 
 
-ALELint                                                       *ALELint-autocmd*
+ALELintPre ALELintPost                 *ALELintPre-autocmd* *ALELintPost-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 unsilent echom 'ALE run!'
-<
+  These |User| autocommands are triggered before and after every lint cycle.
+  It can be used to update statuslines, send notifications, etc.
   The autocmd commands are run with |:silent|, so |:unsilent| is required for
   echoing messges.
 
+  For example to change the color of the statusline while the linter is
+  running:
+>
+    augroup ALEProgress
+        autocmd!
+        autocmd User ALELintPre  hi Statusline ctermfg=darkgrey
+        autocmd User ALELintPOST hi Statusline ctermfg=NONE
+    augroup end
+<
+  Or to display the progress in the statusline:
+>
+    let s:ale_running = 0
+    let l:stl .= '%{s:ale_running ? "[linting]" : ""}'
+    augroup ALEProgress
+        autocmd!
+        autocmd User ALELintPre  let s:ale_running = 1 | redrawstatus
+        autocmd User ALELintPost let s:ale_running = 0 | redrawstatus
+    augroup end
+<
 ===============================================================================
 10. Special Thanks                                         *ale-special-thanks*
 
diff --git a/test/test_alelint_autocmd.vader b/test/test_alelint_autocmd.vader
index 4503005b..b19e6b4e 100644
--- a/test/test_alelint_autocmd.vader
+++ b/test/test_alelint_autocmd.vader
@@ -1,5 +1,6 @@
 Before:
-  let g:success = 0
+  let g:pre_success = 0
+  let g:post_success = 0
   let g:ale_run_synchronously = 1
 
 After:
@@ -10,9 +11,11 @@ After:
 Execute (Run a lint cycle, and check that a variable is set in the autocmd):
   augroup VaderTest
     autocmd!
-    autocmd User ALELint let g:success = 1
+    autocmd User ALELintPre let g:pre_success = 1
+    autocmd User ALELintPost let g:post_success = 1
   augroup end
 
   call ale#Lint()
 
-  AssertEqual g:success, 1
+  AssertEqual g:pre_success, 1
+  AssertEqual g:post_success, 1