Extend statusline interface (#2240)

* Extended statusline.vim to provide an efficient way to access the first errors,warnings,stylerrors,stylewarnings,etc from the loclist.
* Added documentation and help for the new API function.

4 files changed, 171 insertions, 27 deletions

diff --git a/README.md b/README.md
index 42bc554f..4612371d 100644
--- a/README.md
+++ b/README.md
@@ -578,8 +578,16 @@ let g:airline#extensions#ale#enabled = 1
 ```
 
 If you don't want to use vim-airline, you can implement your own statusline
-function without adding any other plugins. ALE provides a function for counting
-the number of problems for this purpose, named `ale#statusline#Count`.
+function without adding any other plugins. ALE provides some functions to 
+assist in this endeavour, including:
+
+* `ale#statusline#Count`: Which returns the number of problems found by ALE
+  for a specified buffer.
+* `ale#statusline#FirstProblem`: Which returns a dictionary containing the
+  full loclist details of the first problem of a specified type found by ALE 
+  in a buffer. (e.g. The first style warning in the current buffer.)
+  This can be useful for displaying more detailed information such as the
+  line number of the first problem in a file.
 
 Say you want to display all errors as one figure, and all non-errors as another
 figure. You can do the following:
@@ -601,7 +609,8 @@ endfunction
 set statusline=%{LinterStatus()}
 ```
 
-See `:help ale#statusline#Count()` for more information.
+See `:help ale#statusline#Count()` or `:help ale#statusline#FirstProblem()`
+for more information.
 
 <a name="faq-lightline"></a>
 
diff --git a/autoload/ale/statusline.vim b/autoload/ale/statusline.vim
index 94fbd6c9..3040985f 100644
--- a/autoload/ale/statusline.vim
+++ b/autoload/ale/statusline.vim
@@ -1,4 +1,5 @@
 " Author: KabbAmine <amine.kabb@gmail.com>
+" Additions by: petpetpetpet <chris@freelanceninjas.com>
 " Description: Statusline related function(s)
 
 function! s:CreateCountDict() abort
@@ -26,19 +27,42 @@ function! ale#statusline#Update(buffer, loclist) abort
     let l:count = s:CreateCountDict()
     let l:count.total = len(l:loclist)
 
+    " Allows easy access to the first instance of each problem type.
+    let l:first_problems = {}
+
     for l:entry in l:loclist
         if l:entry.type is# 'W'
             if get(l:entry, 'sub_type', '') is# 'style'
                 let l:count.style_warning += 1
+
+                if l:count.style_warning == 1
+                    let l:first_problems.style_warning = l:entry
+                endif
             else
                 let l:count.warning += 1
+
+                if l:count.warning == 1
+                    let l:first_problems.warning = l:entry
+                endif
             endif
         elseif l:entry.type is# 'I'
             let l:count.info += 1
+
+            if l:count.info == 1
+                let l:first_problems.info = l:entry
+            endif
         elseif get(l:entry, 'sub_type', '') is# 'style'
             let l:count.style_error += 1
+
+            if l:count.style_error == 1
+                let l:first_problems.style_error = l:entry
+            endif
         else
             let l:count.error += 1
+
+            if l:count.error == 1
+                let l:first_problems.error = l:entry
+            endif
         endif
     endfor
 
@@ -47,24 +71,63 @@ function! ale#statusline#Update(buffer, loclist) abort
     let l:count[1] = l:count.total - l:count[0]
 
     let g:ale_buffer_info[a:buffer].count = l:count
+    let g:ale_buffer_info[a:buffer].first_problems = l:first_problems
 endfunction
 
 " Get the counts for the buffer, and update the counts if needed.
-function! s:GetCounts(buffer) abort
+function! s:UpdateCacheIfNecessary(buffer) abort
+    " Cache is cold, so manually ask for an update.
+    if !has_key(g:ale_buffer_info[a:buffer], 'count')
+        call ale#statusline#Update(a:buffer,
+            \ g:ale_buffer_info[a:buffer].loclist)
+    endif
+endfunction
+
+function! s:BufferCacheExists(buffer) abort
     if !exists('g:ale_buffer_info') || !has_key(g:ale_buffer_info, a:buffer)
-        return s:CreateCountDict()
+        return 0
     endif
 
-    " Cache is cold, so manually ask for an update.
-    if !has_key(g:ale_buffer_info[a:buffer], 'count')
-        call ale#statusline#Update(a:buffer, g:ale_buffer_info[a:buffer].loclist)
+    return 1
+endfunction
+
+" Get the counts for the buffer, and update the counts if needed.
+function! s:GetCounts(buffer) abort
+    if !s:BufferCacheExists(a:buffer)
+        return s:CreateCountDict()
     endif
 
+    call s:UpdateCacheIfNecessary(a:buffer)
+
     return g:ale_buffer_info[a:buffer].count
 endfunction
 
+" Get the dict of first_problems, update the buffer info cache if necessary.
+function! s:GetFirstProblems(buffer) abort
+    if !s:BufferCacheExists(a:buffer)
+        return {}
+    endif
+
+    call s:UpdateCacheIfNecessary(a:buffer)
+
+    return g:ale_buffer_info[a:buffer].first_problems
+endfunction
+
 " Returns a Dictionary with counts for use in third party integrations.
 function! ale#statusline#Count(buffer) abort
     " The Dictionary is copied here before exposing it to other plugins.
     return copy(s:GetCounts(a:buffer))
 endfunction
+
+" Returns a copy of the *first* locline instance of the specified problem
+" type. (so this would allow an external integration to know all the info
+" about the first style warning in the file, for example.)
+function! ale#statusline#FirstProblem(buffer, type) abort
+    let l:first_problems = s:GetFirstProblems(a:buffer)
+
+    if !empty(l:first_problems) && has_key(l:first_problems, a:type)
+        return copy(l:first_problems[a:type])
+    endif
+
+    return {}
+endfunction
diff --git a/doc/ale.txt b/doc/ale.txt
index 836ee29f..2dc4cddc 100644
--- a/doc/ale.txt
+++ b/doc/ale.txt
@@ -3159,6 +3159,21 @@ ale#statusline#Count(buffer)                           *ale#statusline#Count()*
   `total`         -> The total number of problems.
 
 
+ale#statusline#FirstProblem(buffer, type)       *ale#statusline#FirstProblem()*
+
+  Returns a copy of the first entry in the `loclist` that matches the supplied
+  buffer number and problem type. If there is no such enty, an empty dictionary
+  is returned.
+  Problem type should be one of the strings listed below:
+
+  `error`         -> Returns the first `loclist` item with type `E` and
+                     `sub_type != 'style'`
+  `warning`       -> First item with type `W` and `sub_type != 'style'`
+  `info`          -> First item with type `I`
+  `style_error`   -> First item with type `E` and `sub_type == 'style'`
+  `style_warning` -> First item with type `W` and `sub_type == 'style'`
+
+
 b:ale_linted                                                     *b:ale_linted*
 
   `b:ale_linted` is set to the number of times a buffer has been checked by
diff --git a/test/test_statusline.vader b/test/test_statusline.vader
index d928e7ee..f76cbfa9 100644
--- a/test/test_statusline.vader
+++ b/test/test_statusline.vader
@@ -28,25 +28,9 @@ Before:
     return l:res
   endfunction
 
-After:
-  Restore
-
-  delfunction Counts
-
-Execute (Count should be 0 when data is empty):
-  AssertEqual Counts({}), ale#statusline#Count(bufnr(''))
-
-Execute (Count should read data from the cache):
-  let g:ale_buffer_info = {'44': {'count': Counts({'error': 1, 'warning': 2})}}
-  AssertEqual Counts({'error': 1, 'warning': 2}), ale#statusline#Count(44)
-
-Execute (The count should be correct after an update):
-  let g:ale_buffer_info = {'44': {}}
-  call ale#statusline#Update(44, [])
-  AssertEqual Counts({}), ale#statusline#Count(44)
-
-Execute (Count should be match the loclist):
-  let g:ale_buffer_info = {
+  " A test simplified loclist that will be used for some of the
+  " tests in this module.
+  let g:test_buffer_info = {
   \ bufnr(''): {
   \   'loclist': [
   \     {'bufnr': bufnr('') - 1, 'type': 'E'},
@@ -77,6 +61,61 @@ Execute (Count should be match the loclist):
   \   ],
   \ },
   \}
+After:
+  Restore
+
+  delfunction Counts
+  unlet g:test_buffer_info
+
+Execute (Count should be 0 when data is empty):
+  AssertEqual Counts({}), ale#statusline#Count(bufnr(''))
+
+Execute (FirstProblem should be 0 when data is empty):
+  AssertEqual {}, ale#statusline#FirstProblem(bufnr(''), 'error')
+  AssertEqual {}, ale#statusline#FirstProblem(bufnr(''), 'warning')
+  AssertEqual {}, ale#statusline#FirstProblem(bufnr(''), 'style_error')
+  AssertEqual {}, ale#statusline#FirstProblem(bufnr(''), 'style_warning')
+  AssertEqual {}, ale#statusline#FirstProblem(bufnr(''), 'info')
+
+Execute (Count should read data from the cache):
+  let g:ale_buffer_info = {'44': {'count': Counts({'error': 1, 'warning': 2})}}
+  AssertEqual Counts({'error': 1, 'warning': 2}), ale#statusline#Count(44)
+
+Execute (FirstProblem should read data from the cache):
+  let g:ale_buffer_info = 
+    \{"44": 
+        \{'count': 0,
+         \'first_problems':
+              \{'error': {'lnum': 3},
+              \'warning': {'lnum': 44},
+              \'style_error': {'lnum': 22},
+              \'style_warning': {'lnum': 223},
+              \'info': {'lnum': 2}
+           \} 
+        \}
+    \}
+  AssertEqual {'lnum': 3}, ale#statusline#FirstProblem(44, 'error')
+  AssertEqual {'lnum': 44}, ale#statusline#FirstProblem(44, 'warning')
+  AssertEqual {'lnum': 223}, ale#statusline#FirstProblem(44, 'style_warning')
+  AssertEqual {'lnum': 22}, ale#statusline#FirstProblem(44, 'style_error')
+  AssertEqual {'lnum': 2}, ale#statusline#FirstProblem(44, 'info')
+
+Execute (The count should be correct after an update):
+  let g:ale_buffer_info = {'44': {}}
+  call ale#statusline#Update(44, [])
+  AssertEqual Counts({}), ale#statusline#Count(44)
+
+Execute (FirstProblem should be correct after an update):
+  let g:ale_buffer_info = {'44': {}}
+  call ale#statusline#Update(44, [])
+  AssertEqual {}, ale#statusline#FirstProblem(bufnr(''), 'error')
+  AssertEqual {}, ale#statusline#FirstProblem(bufnr(''), 'warning')
+  AssertEqual {}, ale#statusline#FirstProblem(bufnr(''), 'style_error')
+  AssertEqual {}, ale#statusline#FirstProblem(bufnr(''), 'style_warning')
+  AssertEqual {}, ale#statusline#FirstProblem(bufnr(''), 'info')
+
+Execute (Count should match the loclist):
+  let g:ale_buffer_info = g:test_buffer_info
   AssertEqual {
   \ 'error': 1,
   \ 'style_error': 2,
@@ -88,8 +127,22 @@ Execute (Count should be match the loclist):
   \ 'total': 15,
   \}, ale#statusline#Count(bufnr(''))
 
+Execute (FirstProblem should pull the first matching value from the loclist):
+  let g:ale_buffer_info = g:test_buffer_info
+  AssertEqual {'bufnr': bufnr(''), 'type': 'E'}, ale#statusline#FirstProblem(bufnr(''), 'error')
+  AssertEqual {'bufnr': bufnr(''), 'type': 'W'}, ale#statusline#FirstProblem(bufnr(''), 'warning')
+  AssertEqual {'bufnr': bufnr(''), 'type': 'E', 'sub_type': 'style'}, ale#statusline#FirstProblem(bufnr(''), 'style_error')
+  AssertEqual {'bufnr': bufnr(''), 'type': 'W', 'sub_type': 'style'}, ale#statusline#FirstProblem(bufnr(''), 'style_warning')
+  AssertEqual {'bufnr': bufnr(''), 'type': 'I'}, ale#statusline#FirstProblem(bufnr(''), 'info')
+
 Execute (Output should be empty for non-existent buffer):
+  let g:ale_buffer_info = g:test_buffer_info
   AssertEqual Counts({}), ale#statusline#Count(9001)
+  AssertEqual {}, ale#statusline#FirstProblem(9001, 'error')
+  AssertEqual {}, ale#statusline#FirstProblem(9001, 'warning')
+  AssertEqual {}, ale#statusline#FirstProblem(9001, 'style_error')
+  AssertEqual {}, ale#statusline#FirstProblem(9001, 'style_warning')
+  AssertEqual {}, ale#statusline#FirstProblem(9001, 'info')
 
 Execute(ale#statusline#Update shouldn't blow up when globals are undefined):
   unlet! g:ale_statusline_format
@@ -98,3 +151,7 @@ Execute(ale#statusline#Update shouldn't blow up when globals are undefined):
 Execute(ale#statusline#Count should return 0 counts when globals are undefined):
   unlet! g:ale_statusline_format
   AssertEqual Counts({}), ale#statusline#Count(1)
+
+Execute(FirstProblem should return an empty dict when globals are undefined):
+  unlet! g:ale_statusline_format
+  AssertEqual {}, ale#statusline#FirstProblem(bufnr(''), 'info')