add an option to allow users to format the statusline flag

Add the syntastic_stl_format flag and doc it under
:help syntastic_stl_format. This allows the user to control what
information is displayed in the syntastic statusline flag.

doc/syntastic.txt

@@ -88,13 +88,8 @@ Something like this could be more useful: >
     set statusline+=%{SyntasticStatuslineFlag()}
     set statusline+=%*
 <
-When syntax errors are detected, the following will be displayed on your
-statusline: >
-    [syntax:X(Y)]
-<
-Where X is the line number of the first error and Y is the total number of
-errors. Note that "(Y)" only appears  if there is more than one error.
-
+When syntax errors are detected a flag will be shown. The content of the flag
+is derived from the |syntastic_stl_format| option
 ------------------------------------------------------------------------------
 2.2. Error signs                                       *syntastic-error-signs*
 
@@ -166,6 +161,37 @@ this option has the following effects:
     let g:syntastic_quiet_warnings=1
 <
 
+                                                      *'syntastic_stl_format'*
+
+Default: [Syntax: line:%F (%t)]
+Use this option to control what the syntastic statusline text contains. Several
+magic flags are availble to insert information:
+    %e - number of errors
+    %w - number of warnings
+    %t - total number of warnings and errors
+    %fe - line number of first error
+    %fw - line number of first warning
+    %F - line number of first warning or error
+
+Several additional flags are available to hide text under certain conditions:
+    %E{...} - hide the text in the brackets unless there are errors
+    %W{...} - hide the text in the brackets unless there are warnings
+    %B{...} - hide the text in the brackets unless there are both warnings AND
+              errors
+These flags cant be nested.
+
+Example: >
+    let g:syntastic_stl_format = '[%E{Err: %fe #%e}%B{, }%W{Warn: %fw #%w}]'
+<
+If this format is used and the current buffer has 5 errors and 1 warning
+starting on lines 20 and 10 respectively then this would appear on the
+statusline: >
+    [Err: 20 #5, Warn: 10 #1]
+<
+If the buffer had 2 warnings, starting on line 5 then this would appear: >
+    [Warn: 5 #2]
+<
+
                                               *'syntastic_disabled_filetypes'*
 Use this option to disable syntax checking on selected filetypes by default.
 Should be set to a list of filetypes, e.g. >

plugin/syntastic.vim

@@ -39,6 +39,10 @@ if !exists("g:syntastic_disabled_filetypes")
     let g:syntastic_disabled_filetypes = []
 endif
 
+if !exists("g:syntastic_stl_format")
+    let g:syntastic_stl_format = '[Syntax: line:%F (%t)]'
+endif
+
 "load all the syntax checkers
 runtime! syntax_checkers/*.vim
 
@@ -111,6 +115,14 @@ function! s:ErrorsForType(type)
     return filter(copy(b:syntastic_loclist), 'v:val["type"] ==? "' . a:type . '"')
 endfunction
 
+function s:Errors()
+    return extend(s:ErrorsForType("E"), s:ErrorsForType(''))
+endfunction
+
+function s:Warnings()
+    return s:ErrorsForType("W")
+endfunction
+
 if g:syntastic_enable_signs
     "use >> to display syntax errors in the sign column
     sign define SyntasticError text=>> texthl=error
@@ -180,33 +192,41 @@ endfunction
 
 command Errors call s:ShowLocList()
 
-"return [syntax:X(Y)] if syntax errors are detected in the buffer, where X is the
-"line number of the first error and Y is the number of errors detected. (Y) is
-"only displayed if > 1 errors are detected
+"return a string representing the state of buffer according to
+"g:syntastic_stl_format
 "
 "return '' if no errors are cached for the buffer
 function! SyntasticStatuslineFlag()
     if s:BufHasErrorsOrWarningsToDisplay()
+        let errors = s:Errors()
+        let warnings = s:Warnings()
 
-        let first_err_line = b:syntastic_loclist[0]['lnum']
-        if g:syntastic_quiet_warnings
-            let first_err_line = s:ErrorsForType('E')[0]['lnum']
-        endif
+        let output = g:syntastic_stl_format
 
-        let err_count = len(b:syntastic_loclist)
-        if g:syntastic_quiet_warnings
-            let err_count = len(s:ErrorsForType('E'))
-        endif
+        "hide stuff wrapped in %E(...) unless there are errors
+        let output = substitute(output, '\C%E{\([^}]*\)}', len(errors) ? '\1' : '' , 'g')
 
-        let toReturn = '[syntax:' . first_err_line
+        "hide stuff wrapped in %W(...) unless there are warnings
+        let output = substitute(output, '\C%W{\([^}]*\)}', len(warnings) ? '\1' : '' , 'g')
 
-        if err_count > 1
-            let toReturn .= '(' . err_count . ')'
-        endif
+        "hide stuff wrapped in %B(...) unless there are both errors and warnings
+        let output = substitute(output, '\C%B{\([^}]*\)}', (len(warnings) && len(errors)) ? '\1' : '' , 'g')
 
-        let toReturn .= ']'
+        "sub in the total errors/warnings/both
+        let output = substitute(output, '\C%w', len(warnings), 'g')
+        let output = substitute(output, '\C%e', len(errors), 'g')
+        let output = substitute(output, '\C%t', len(b:syntastic_loclist), 'g')
 
-        return toReturn
+        "first error/warning line num
+        let output = substitute(output, '\C%F', b:syntastic_loclist[0]['lnum'], 'g')
+
+        "first error line num
+        let output = substitute(output, '\C%fe', len(errors) ? errors[0]['lnum'] : '', 'g')
+
+        "first warning line num
+        let output = substitute(output, '\C%fw', len(warnings) ? warnings[0]['lnum'] : '', 'g')
+
+        return output
     else
         return ''
     endif