Add g:FerretAutojump

There is a little bit of fragility here because the user can override
the handler behavior with `g:FerretQFHandler` (for example, my use of
`wincmd p` here assumes you've switched focus with `copen` rather than
`cwindow`, but short of removing that functionality I am not sure how
one would avoid this). As it is, the `wincmd` can do the wrong thing, so
this feature is decidedly fragile. eg:

- run a search, and leaving focus in the quickfix listing
- let g:FerretDispatch=0
- let g:FerretAutojump=0
- our wincmd here rotates us out of the quickfix window

Related #21

autoload/ferret/private.vim

@@ -26,6 +26,15 @@ function! s:dispatch()
   return l:dispatch && exists(':Make') == 2
 endfunction
 
+" Convenience function to get/sanitize the current g:FerretAutojump setting.
+function! s:autojump()
+  let l:autojump=get(g:, 'FerretAutojump', 1)
+  if l:autojump != 0 && l:autojump != 1 && l:autojump != 2
+    let l:autojump=1
+  endif
+  return l:autojump
+endfunction
+
 " Use `input()` to show error output to user. Ideally, we would do this in a way
 " that didn't require user interaction, but this is the only reliable mechanism
 " that works for all cases. Alternatives considered:
@@ -152,6 +161,7 @@ endfunction
 
 function! ferret#private#ack(...) abort
   let l:command=s:parse(a:000)
+  let l:autojump=s:autojump()
   call ferret#private#hlsearch()
 
   if empty(&grepprg)
@@ -163,9 +173,16 @@ function! ferret#private#ack(...) abort
     if has('autocmd')
       augroup FerretPostQF
         autocmd!
-        autocmd QuickfixCmdPost cgetfile call ferret#private#post('qf')
+        if l:autojump == 0
+          autocmd QuickfixCmdPost cgetfile call ferret#private#post('qf') | wincmd p
+        elseif l:autojump == 1
+          autocmd QuickfixCmdPost cgetfile call ferret#private#post('qf')
+        elseif l:autojump == 2
+          autocmd QuickfixCmdPost cgetfile call ferret#private#post('qf') | silent! cc
+        endif
       augroup END
     endif
+
     let l:original_makeprg=&l:makeprg
     let l:original_errorformat=&l:errorformat
     try
@@ -179,22 +196,46 @@ function! ferret#private#ack(...) abort
       let &l:errorformat=l:original_errorformat
     endtry
   else
-    cexpr system(&grepprg . ' ' . l:command)
-    execute get(g:, 'FerretQFHandler', 'botright cwindow')
+    " Not using vim-dispatch.
+    let l:handler=get(g:, 'FerretQFHandler', 'botright copen')
+    if l:autojump == 0
+      cgetexpr system(&grepprg . ' ' . l:command) " Don't jump to first error.
+      execute l:handler
+      wincmd p " Go back to whatever window was previously focused.
+    elseif l:autojump == 1
+      cgetexpr system(&grepprg . ' ' . l:command) " Don't jump to first error.
+      execute l:handler
+    elseif l:autojump == 2
+      cexpr system(&grepprg . ' ' . l:command) " Jump to first error.
+      execute l:handler
+      silent! cc
+    endif
     call ferret#private#post('qf')
   endif
 endfunction
 
 function! ferret#private#lack(...) abort
   let l:command=s:parse(a:000)
+  let l:autojump=s:autojump()
   call ferret#private#hlsearch()
 
   if empty(&grepprg)
     return
   endif
 
-  lexpr system(&grepprg . ' ' . l:command)
-  execute get(g:, 'FerretLLHandler', 'lwindow')
+  let l:handler=get(g:, 'FerretLLHandler', 'lopen')
+  if l:autojump == 0
+    lgetexpr system(&grepprg . ' ' . l:command) " Don't jump to first error.
+    execute l:handler
+    wincmd p " Go back to whatever window was previously focused.
+  elseif l:autojump == 1
+    lgetexpr system(&grepprg . ' ' . l:command) " Don't jump to first error.
+    execute l:handler
+  elseif l:autojump == 2
+    lexpr system(&grepprg . ' ' . l:command) " Jump to first error.
+    execute l:handler
+    silent! ll
+  endif
   call ferret#private#post('location')
 endfunction
 

doc/ferret.txt

@@ -204,6 +204,21 @@ OPTIONS                                                        *ferret-options*
   'hlsearch', set |g:FerretHlsearch| to 1 or 0: >
 
     let g:FerretHlsearch=0
+<
+                                                             *g:FerretAutojump*
+  |g:FerretAutojump|                                       number (default: 1)
+
+  Controls whether Ferret will automatically jump to the first found match.
+
+  - Set to 0, Ferret will show the search results but perform no jump.
+  - Set to 1, Ferret will show the search results and focus the result
+    listing.
+  - Set to 2, Ferret will show the search results and jump to the first found
+    match.
+
+  Example override: >
+
+    let g:FerretAutojump=2
 <
                                                            *g:FerretQFCommands*
   |g:FerretQFCommands|                                     boolean (default: 1)
@@ -245,7 +260,7 @@ OPTIONS                                                        *ferret-options*
     let g:FerretQFOptions=0
 <
                                                             *g:FerretQFHandler*
-  |g:FerretQFHandler|                      string (default: "botright cwindow")
+  |g:FerretQFHandler|                        string (default: "botright copen")
 
   Defines the command to open the |quickfix| window to display the results of
   a synchronous |:Ack| operation.
@@ -259,7 +274,7 @@ OPTIONS                                                        *ferret-options*
   the display of the window itself.
 
                                                             *g:FerretLLHandler*
-  |g:FerretLLHandler|                               string (default: "lwindow")
+  |g:FerretLLHandler|                                 string (default: "lopen")
 
   Just like |g:FerretQFHandler|, but applied to |location-list|.
 
@@ -551,6 +566,14 @@ order):
 
 HISTORY                                                        *ferret-history*
 
+1.2 (not yet released)
+
+- Added |g:FerretAutojump| to suppress or enable automatically jumping to the
+  first search result.
+- Changed |g:FerretQFHandler| to default to "botright copen" and
+  |g:FerretLLHandler| to default to "lopen" for more consistent behavior with
+  and without dispatch.vim.
+
 1.1.1 (7 March 2016)
 
 - Fix another edge case when searching for patterns containing "#", only