Merge pull request #1543 from vancluever/f-add-JobStartedAutoCmd

Add ALEJobStarted User autocommand event

README.md

@@ -524,17 +524,21 @@ Will give you:
 ### 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)
-events when a lint or fix cycle are started and stopped. These events can be
+events when a lint or fix cycle are started and stopped. There is also an event
-used to call arbitrary functions before and after ALE stops linting.
+that runs when a linter job has been successfully started. These events can be
+used to call arbitrary functions during these respective parts of the ALE's
+operation.
 
 ```vim
 augroup YourGroup
     autocmd!
-    autocmd User ALELintPre  call YourFunction()
+    autocmd User ALELintPre    call YourFunction()
-    autocmd User ALELintPost call YourFunction()
+    autocmd User ALELintPost   call YourFunction()
 
-    autocmd User ALEFixPre   call YourFunction()
+    autocmd User ALEJobStarted call YourFunction()
-    autocmd User ALEFixPost  call YourFunction()
+
+    autocmd User ALEFixPre     call YourFunction()
+    autocmd User ALEFixPost    call YourFunction()
 augroup END
 ```
 

autoload/ale/engine.vim

@@ -586,6 +586,8 @@ function! s:RunJob(options) abort
         \   'output': [],
         \   'next_chain_index': l:next_chain_index,
         \}
+
+        silent doautocmd <nomodeline> User ALEJobStarted
     endif
 
     if g:ale_history_enabled

doc/ale.txt

@@ -2459,7 +2459,15 @@ ALEFixPost                                                 *ALEFixPost-autocmd*
         autocmd User ALELintPre  let s:ale_running = 1 | redrawstatus
         autocmd User ALELintPost let s:ale_running = 0 | redrawstatus
     augroup end
+
 <
+ALEJobStarted                                           *ALEJobStarted-autocmd*
+
+  This |User| autocommand is triggered immediately after a job is successfully
+  run. This provides better accuracy for checking linter status with
+  |ale#engine#IsCheckingBuffer()| over |ALELintPre-autocmd|, which is actually
+  triggered before any linters are executed.
+
 
 ===============================================================================
 10. Special Thanks                                         *ale-special-thanks*

test/test_alejobstarted_autocmd.vader

@@ -0,0 +1,42 @@
+Given testft (An empty file):
+
+Before:
+  let g:job_started_success = 0
+  let g:ale_run_synchronously = 1
+
+  unlet! b:ale_linted
+
+  function! TestCallback(buffer, output)
+    return []
+  endfunction
+
+  call ale#linter#Define('testft', {
+  \ 'name': 'testlinter',
+  \ 'callback': 'TestCallback',
+  \ 'executable': has('win32') ? 'cmd' : 'true',
+  \ 'command': 'true',
+  \})
+
+After:
+  let g:ale_run_synchronously = 0
+  let g:ale_buffer_info = {}
+
+  try
+    augroup! VaderTest
+  catch
+  endtry
+
+  unlet! g:job_started_success
+
+  delfunction TestCallback
+  call ale#linter#Reset()
+
+Execute(Run a lint cycle with an actual job to check for ALEJobStarted):
+  augroup VaderTest
+    autocmd!
+    autocmd User ALEJobStarted let g:job_started_success = 1
+  augroup end
+
+  call ale#Lint()
+
+  AssertEqual g:job_started_success, 1

test/test_checkingbuffer_autocmd.vader

@@ -0,0 +1,57 @@
+Given testft (An empty file):
+
+Before:
+  Save g:ale_run_synchronously
+  Save g:ale_buffer_info
+  
+  let g:ale_run_synchronously = 1
+  let g:ale_buffer_info = {}
+
+  let g:checking_buffer = 0
+
+  unlet! b:ale_linted
+
+  function! TestCallback(buffer, output)
+    return []
+  endfunction
+
+  call ale#linter#Define('testft', {
+  \ 'name': 'testlinter',
+  \ 'callback': 'TestCallback',
+  \ 'executable': has('win32') ? 'cmd' : 'true',
+  \ 'command': 'true',
+  \})
+
+After:
+  Restore
+
+  unlet! g:checking_buffer
+  
+  delfunction TestCallback
+  call ale#linter#Reset()
+  
+  augroup VaderTest
+    autocmd!
+  augroup end
+
+  augroup! VaderTest
+
+Execute(ALELintPre should not return success on ale#engine#IsCheckingBuffer):
+  augroup VaderTest
+    autocmd!
+    autocmd User ALELintPre let g:checking_buffer = ale#engine#IsCheckingBuffer(bufnr('')) ? 1 : 0 
+  augroup end
+
+  call ale#Lint()
+
+  AssertEqual g:checking_buffer, 0
+
+Execute(ALEJobStarted should return success on ale#engine#IsCheckingBuffer):
+  augroup VaderTest
+    autocmd!
+    autocmd User ALEJobStarted let g:checking_buffer = ale#engine#IsCheckingBuffer(bufnr('')) ? 1 : 0 
+  augroup end
+
+  call ale#Lint()
+
+  AssertEqual g:checking_buffer, 1