]> git.wincent.com - docvim.git/commitdiff
Add integration test files
authorGreg Hurrell <greg@hurrell.net>
Fri, 10 Jun 2016 15:29:05 +0000 (08:29 -0700)
committerGreg Hurrell <greg@hurrell.net>
Fri, 10 Jun 2016 15:33:45 +0000 (08:33 -0700)
Copied into place with:

git --git-dir ~/code/ferret/.git archive --prefix=ferret/input/ master | tar -x -C tests/fixtures/integration -f -
git --git-dir ~/code/scalpel/.git archive --prefix=scalpel/input/ master | tar -x -C tests/fixtures/integration -f -

Will add more of these, I guess, as I start using docvim in more places.

20 files changed:
tests/fixtures/integration/ferret/input/.gitignore [new file with mode: 0644]
tests/fixtures/integration/ferret/input/.mailmap [new file with mode: 0644]
tests/fixtures/integration/ferret/input/LICENSE.txt [new file with mode: 0644]
tests/fixtures/integration/ferret/input/README.md [new file with mode: 0644]
tests/fixtures/integration/ferret/input/autoload/ferret/private.vim [new file with mode: 0644]
tests/fixtures/integration/ferret/input/autoload/ferret/private/async.vim [new file with mode: 0644]
tests/fixtures/integration/ferret/input/autoload/ferret/private/dispatch.vim [new file with mode: 0644]
tests/fixtures/integration/ferret/input/autoload/ferret/private/vanilla.vim [new file with mode: 0644]
tests/fixtures/integration/ferret/input/doc/.gitignore [new file with mode: 0644]
tests/fixtures/integration/ferret/input/doc/ferret.txt [new file with mode: 0644]
tests/fixtures/integration/ferret/input/ftplugin/qf.vim [new file with mode: 0644]
tests/fixtures/integration/ferret/input/plugin/ferret.vim [new file with mode: 0644]
tests/fixtures/integration/ferret/input/test.rb [new file with mode: 0755]
tests/fixtures/integration/scalpel/input/.gitignore [new file with mode: 0644]
tests/fixtures/integration/scalpel/input/LICENSE.md [new file with mode: 0644]
tests/fixtures/integration/scalpel/input/README.md [new file with mode: 0644]
tests/fixtures/integration/scalpel/input/autoload/scalpel.vim [new file with mode: 0644]
tests/fixtures/integration/scalpel/input/doc/.gitignore [new file with mode: 0644]
tests/fixtures/integration/scalpel/input/doc/scalpel.txt [new file with mode: 0644]
tests/fixtures/integration/scalpel/input/plugin/scalpel.vim [new file with mode: 0644]

diff --git a/tests/fixtures/integration/ferret/input/.gitignore b/tests/fixtures/integration/ferret/input/.gitignore
new file mode 100644 (file)
index 0000000..20cb71e
--- /dev/null
@@ -0,0 +1 @@
+/*.zip
diff --git a/tests/fixtures/integration/ferret/input/.mailmap b/tests/fixtures/integration/ferret/input/.mailmap
new file mode 100644 (file)
index 0000000..38b1492
--- /dev/null
@@ -0,0 +1,2 @@
+Daniel Silva <daniel.s.silva@live.com> Daniel Silva <daniel.silva@project1.com.br>
+Joe Lencioni <joe.lencioni@gmail.com> Joe Lencioni <joe.lencioni@brigade.com>
diff --git a/tests/fixtures/integration/ferret/input/LICENSE.txt b/tests/fixtures/integration/ferret/input/LICENSE.txt
new file mode 100644 (file)
index 0000000..3906829
--- /dev/null
@@ -0,0 +1,22 @@
+Copyright 2015-present Greg Hurrell. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
diff --git a/tests/fixtures/integration/ferret/input/README.md b/tests/fixtures/integration/ferret/input/README.md
new file mode 100644 (file)
index 0000000..332c36a
--- /dev/null
@@ -0,0 +1,465 @@
+<p align="center">
+<img src="https://raw.githubusercontent.com/wincent/ferret/media/ferret.jpg" />
+<img src="https://raw.githubusercontent.com/wincent/ferret/media/ferret.gif" />
+</p>
+# ferret
+
+## Intro
+
+> "ferret (verb)<br />(ferret something out) search tenaciously for and find something: she had the ability to ferret out the facts."
+
+<p align="right"><a name="ferret-features" href="#user-content-ferret-features"><code>ferret-features</code></a></p>
+Ferret improves Vim's multi-file search in four ways:
+
+### 1. Powerful multi-file search
+
+Ferret provides an <strong>[`:Ack`](#user-content-ack)</strong> command for searching across multiple files using The Silver Searcher (https://github.com/ggreer/the_silver_searcher), Ack (http://beyondgrep.com/), or Grep (http://www.gnu.org/software/grep/). Support for passing options through to the underlying search command exists, along with the ability to use full regular expression syntax without doing special escaping.
+
+Shortcut mappings are provided to start an <strong>[`:Ack`](#user-content-ack)</strong> search (<leader>a) or to search for the word currently under the cursor (<leader>s).
+
+Results are normally displayed in the <strong>`quickfix`</strong> window, but Ferret also provides a <strong>[`:Lack`](#user-content-lack)</strong> command that behaves like <strong>[`:Ack`](#user-content-ack)</strong> but uses the <strong>`location-list`</strong> instead, and a <leader>l mapping as a shortcut to <strong>[`:Lack`](#user-content-lack)</strong>.
+
+Finally, Ferret offers integration with dispatch.vim (https://github.com/tpope/vim-dispatch), which enables asynchronous searching despite the fact that Vim itself is single-threaded.
+
+### 2. Streamlined multi-file replace
+
+The companion to <strong>[`:Ack`](#user-content-ack)</strong> is <strong>[`:Acks`](#user-content-acks)</strong> (mnemonic: "Ack substitute", accessible via shortcut <leader>r), which allows you to run a multi-file replace across all the files placed in the <strong>`quickfix`</strong> window by a previous invocation of <strong>[`:Ack`](#user-content-ack)</strong>.
+
+### 3. Quickfix listing enhancements
+
+The <strong>`quickfix`</strong> listing itself is enhanced with settings to improve its usability, and natural mappings that allow quick removal of items from the list (for example, you can reduce clutter in the listing by removing lines that you don't intend to make changes to).
+
+Additionally, Vim's <strong>`:cn`</strong>, <strong>`:cp`</strong>, <strong>`:cnf`</strong> and <strong>`:cpf`</strong> commands are tweaked to make it easier to immediately identify matches by centering them within the viewport.
+
+### 4. Easy operations on files in the quickfix listing
+
+Finally, Ferret provides a <strong>[`:Qargs`](#user-content-qargs)</strong> command that puts the files currently in the <strong>`quickfix`</strong> listing into the <strong>`:args`</strong> list, where they can be operated on in bulk via the <strong>`:argdo`</strong> command. This is what's used under the covers by <strong>[`:Acks`](#user-content-acks)</strong> to do its work.
+
+## Installation
+
+To install Ferret, use your plug-in management system of choice.
+
+If you don't have a "plug-in management system of choice", I recommend Pathogen (https://github.com/tpope/vim-pathogen) due to its simplicity and robustness. Assuming that you have Pathogen installed and configured, and that you want to install Ferret into `~/.vim/bundle`, you can do so with:
+
+```
+git clone https://github.com/wincent/ferret.git ~/.vim/bundle/ferret
+```
+
+Alternatively, if you use a Git submodule for each Vim plug-in, you could do the following after `cd`-ing into the top-level of your Git superproject:
+
+```
+git submodule add https://github.com/wincent/ferret.git ~/vim/bundle/ferret
+git submodule init
+```
+
+To generate help tags under Pathogen, you can do so from inside Vim with:
+
+```
+:call pathogen#helptags()
+```
+
+## Options
+
+## Commands
+
+<p align="right"><a name="ack" href="#user-content-ack"><code>:Ack</code></a></p>
+### `:Ack {pattern} {options}`
+
+Searches for {pattern} in all the files under the current directory (see <strong>`:pwd`</strong>), unless otherwise overridden via {options}, and displays the results in the <strong>`quickfix`</strong> listing.
+
+`ag` (The Silver Searcher) will be used preferentially if present on the system, because it is faster, falling back to `ack` and then `grep` as needed.
+
+If dispatch.vim is installed the search process will run asynchronously via the <strong>`:Make`</strong> command, otherwise it will be run synchronously via <strong>`:cexpr`</strong>. Asynchronous searches are preferred because they do not block, despite the fact that Vim itself is single threaded. The <strong>`g:FerretDispatch`</strong> option can be used to prevent the use of dispatch.vim.
+
+The {pattern} is passed through as-is to the underlying search program, and no escaping is required other than preceding spaces by a single backslash. For example, to search for "\bfoo[0-9]{2} bar\b" (ie. using `ag`'s Perl-style regular expression syntax), you could do:
+
+```
+:Ack \bfoo[0-9]{2}\ bar\b
+```
+
+Likewise, {options} are passed through. In this example, we pass the `-w` option (to search on word boundaries), and scope the search to the "foo" and "bar" subdirectories: >
+
+```
+:Ack -w something foo bar
+```
+
+As a convenience <leader>a is set-up (<strong>[`<Plug>(FerretAck)`](#user-content-plugferretack)</strong>) as a shortcut to enter <strong>`Cmdline-mode`</strong> with `:Ack` inserted on the <strong>`Cmdline`</strong>. Likewise <leader>s (<strong>[`<Plug>(FerretAckWord)`](#user-content-plugferretackword)</strong>) is a shortcut for running <strong>[`:Ack`](#user-content-ack)</strong> with the word currently under the cursor.
+
+<p align="right"><a name="lack" href="#user-content-lack"><code>:Lack</code></a></p>
+### `:Lack {pattern} {options}`
+
+Just like <strong>[`:Ack`](#user-content-ack)</strong>, but instead of using the <strong>`quickfix`</strong> listing, which is global across an entire Vim instance, it uses the <strong>`location-list`</strong>, which is a per-window construct.
+
+Note that <strong>[`:Lack`](#user-content-lack)</strong> always runs synchronously via <strong>`:cexpr`</strong>, because dispatch.vim doesn't currently support the <strong>`location-list`</strong>.
+
+<p align="right"><a name="acks" href="#user-content-acks"><code>:Acks</code></a></p>
+### `:Acks /{pattern}/{replacement}/`
+
+Takes all of the files currently in the <strong>`quickfix`</strong> listing and performs a substitution of all instances of {pattern} (a standard Vim search <strong>`pattern`</strong>) by {replacement}.
+
+A typical sequence consists of an <strong>[`:Ack`](#user-content-ack)</strong> invocation to populate the <strong>`quickfix`</strong> listing and then <strong>[`:Acks`](#user-content-acks)</strong> (mnemonic: "Ack substitute") to perform replacements. For example, to replace "foo" with "bar" across all files in the current directory:
+
+```
+:Ack foo
+:Acks /foo/bar/
+```
+
+<p align="right"><a name="qargs" href="#user-content-qargs"><code>:Qargs</code></a></p>
+### `:Qargs`
+
+This is a utility function that is used by the <strong>[`:Acks`](#user-content-acks)</strong> command but is also generally useful enough to warrant being exposed publicly.
+
+It takes the files currently in the <strong>`quickfix`</strong> listing and sets them as <strong>`:args`</strong> so that they can be operated on en masse via the <strong>`:argdo`</strong> command.
+
+## Mappings
+
+### Circumstances where mappings do not get set up
+
+Note that Ferret will not try to set up the <leader> mappings if any of the following are true:
+
+- A mapping for already exists.
+- An alternative mapping for the same functionality has already been set up from a <strong>`.vimrc`</strong>.
+- The mapping has been suppressed by setting <strong>`g:FerretMap`</strong> to 1 in your <strong>`.vimrc`</strong>.
+
+### Mappings specific to the quickfix window
+
+Additionally, Ferret will set up special mappings in <strong>`quickfix`</strong> listings, unless prevented from doing so by <strong>`g:FerretQFMap`</strong>:
+
+- `d` (<strong>`visual-mode`</strong>): delete visual selection
+- `dd` (<strong>`Normal-mode`</strong>): delete current line
+- `d`{motion} (<strong>`Normal-mode`</strong>): delete range indicated by {motion}
+
+### `<Plug>(FerretAck)`
+
+Ferret maps <leader>a to <strong>[`<Plug>(FerretAck)`](#user-content-plugferretack)</strong>, which triggers the <strong>[`:Ack`](#user-content-ack)</strong> command. To use an alternative mapping instead, create a different one in your <strong>`.vimrc`</strong> instead using <strong>`:nmap`</strong>:
+
+```
+" Instead of <leader>a, use <leader>x.
+nmap <leader>x <Plug>(FerretAck)
+```
+
+### `<Plug>(FerretLack)`
+
+Ferret maps <leader>l to <strong>[`<Plug>(FerretLack)`](#user-content-plugferretlack)</strong>, which triggers the <strong>[`:Lack`](#user-content-lack)</strong> command. To use an alternative mapping instead, create a different one in your <strong>`.vimrc`</strong> instead using <strong>`:nmap`</strong>:
+
+```
+" Instead of <leader>l, use <leader>y.
+nmap <leader>y <Plug>(FerretLack)
+```
+
+### `<Plug>(FerretAckWord)`
+
+Ferret maps <leader>s (mnemonix: "selection) to <strong>[`<Plug>(FerretAckWord)`](#user-content-plugferretackword)</strong>, which uses <strong>[`:Ack`](#user-content-ack)</strong> to search for the word currently under the cursor. To use an alternative mapping instead, create a different one in your <strong>`.vimrc`</strong> instead using <strong>`:nmap`</strong>:
+
+```
+" Instead of <leader>s, use <leader>z.
+nmap <leader>z <Plug>(FerretAckWord)
+```
+
+### `<Plug>(FerretAcks)`
+
+Ferret maps <leader>r (mnemonic: "replace") to <strong>[`<Plug>(FerretAcks)`](#user-content-plugferretacks)</strong>, which triggers the <strong>[`:Acks`](#user-content-acks)</strong> command and fills the prompt with the last search term from Ferret. to use an alternative mapping instead, create a different one in your <strong>`.vimrc`</strong> instead using <strong>`:nmap`</strong>:
+
+```
+" Instead of <leader>r, use <leader>u.
+nmap <leader>u <Plug>(FerretAcks)
+```
+
+<p align="right"><a name="gferretdispatch" href="#user-content-gferretdispatch"><code>g:FerretDispatch</code></a></p>
+### `g:FerretDispatch` (boolean, default: 1)
+
+Controls whether to use vim-dispatch (and specifically, <strong>`:Make`</strong>) to run <strong>[`:Ack`](#user-content-ack)</strong> searches asynchronously, when available. To prevent vim-dispatch from being used, set to 0:
+
+```
+let g:FerretDispatch=0
+```
+
+<p align="right"><a name="gferrethlsearch" href="#user-content-gferrethlsearch"><code>g:FerretHlsearch</code></a></p>
+### `g:FerretHlsearch` (boolean, default: none)
+
+Controls whether Ferret should attempt to highlight the search pattern when running <strong>[`:Ack`](#user-content-ack)</strong> or <strong>[`:Lack`](#user-content-lack)</strong>. If left unset, Ferret will respect the current 'hlsearch' setting. To force highlighting on or off irrespective of 'hlsearch', set <strong>`g:FerretHlsearch`</strong> to 1 (on) or 0 (off):
+
+```
+let g:FerretHlsearch=0
+```
+
+<p align="right"><a name="gferretqfoptions" href="#user-content-gferretqfoptions"><code>g:FerretQFOptions</code></a></p>
+### `g:FerretQFOptions` (boolean, default: 1)
+
+Controls whether to set up setting overrides for <strong>`quickfix`</strong> windows. These are various settings, such as <strong>`norelativenumber`</strong>, <strong>`nolist`</strong> and <strong>`nowrap`</strong>, that are intended to make the <strong>`quickfix`</strong> window, which is typically very small relative to other windows, more usable.
+
+A full list of overridden settings can be found in <strong>[`ferret-overrides`](#user-content-ferret-overrides)</strong>.
+
+To prevent the custom settings from being applied, set <strong>`g:FerretQFOptions`</strong> to 0:
+
+```
+let g:FerretQFOptions=0
+```
+
+<p align="right"><a name="gferretqfmap" href="#user-content-gferretqfmap"><code>g:FerretQFMap</code></a></p>
+### `g:FerretQFMap` (boolean, default: 1)
+
+Controls whether to set up mappings in the <strong>`quickfix`</strong> results window for deleting results. The mappings include:
+
+- `d` (<strong>`visual-mode`</strong>): delete visual selection
+- `dd` (<strong>`Normal-mode`</strong>): delete current line
+- `d`{motion} (<strong>`Normal-mode`</strong>): delete range indicated by {motion}
+
+To prevent these mappings from being set up, set to 0:
+
+```
+let g:FerretQFMap=0
+```
+
+<p align="right"><a name="gferretloaded" href="#user-content-gferretloaded"><code>g:FerretLoaded</code></a></p>
+### `g:FerretLoaded` (any, default: none)
+
+To prevent Ferret from being loaded, set <strong>`g:FerretLoaded`</strong> to any value in your <strong>`.vimrc`</strong>. For example:
+
+```
+let g:FerretLoaded=1
+```
+
+<p align="right"><a name="gferretmap" href="#user-content-gferretmap"><code>g:FerretMap</code></a></p>
+### `g:FerretMap` (boolean, default: 1)
+
+Controls whether to set up the Ferret mappings, such as <strong>[`<Plug>(FerretAck)`](#user-content-plugferretack)</strong> (see <strong>[`ferret-mappings`](#user-content-ferret-mappings)</strong> for a full list). To prevent any mapping from being configured, set to 0:
+
+```
+let g:FerretMap=0
+```
+
+<p align="right"><a name="gferretqfcommands" href="#user-content-gferretqfcommands"><code>g:FerretQFCommands</code></a></p>
+### `g:FerretQFCommands` (boolean, default: 1)
+
+Controls whether to set up custom versions of the <strong>`quickfix`</strong> commands, <strong>`:cn`</strong>, <strong>`:cnf`</strong>, <strong>`:cp`</strong> an <strong>`:cpf`</strong>. These overrides vertically center the match within the viewport on each jump. To prevent the custom versions from being configured, set to 0:
+
+```
+let g:FerretQFCommands=0
+```
+
+## Custom autocommands
+
+<p align="right"><a name="ferretdidwrite" href="#user-content-ferretdidwrite"><code>FerretDidWrite</code></a> <a name="ferretwillwrite" href="#user-content-ferretwillwrite"><code>FerretWillWrite</code></a></p>
+For maximum compatibility with other plug-ins, Ferret runs the following "User" autocommands before and after running the file writing operations during <strong>[`:Acks`](#user-content-acks)</strong>:
+
+- FerretWillWrite
+- FerretDidWrite
+
+For example, to call a pair of custom functions in response to these events, you might do:
+
+```
+autocmd! User FerretWillWrite
+autocmd User FerretWillWrite call CustomWillWrite()
+autocmd! User FerretDidWrite
+autocmd User FerretDidWrite call CustomDidWrite()
+```
+
+## Overrides
+
+Ferret overrides the 'grepformat' and 'grepprg' settings, preferentially setting `ag`, `ack` or `grep` as the 'grepprg' (in that order) and configuring a suitable 'grepformat'.
+
+Additionally, Ferret includes an <strong>`ftplugin`</strong> for the <strong>`quickfix`</strong> listing that adjusts a number of settings to improve the usability of search results.
+
+<p align="right"><a name="ferret-nolist" href="#user-content-ferret-nolist"><code>ferret-nolist</code></a></p>
+'nolist'
+
+Turned off to reduce visual clutter in the search results, and because 'list' is most useful in files that are being actively edited, which is not the case for <strong>`quickfix`</strong> results.
+
+<p align="right"><a name="ferret-norelativenumber" href="#user-content-ferret-norelativenumber"><code>ferret-norelativenumber</code></a></p>
+'norelativenumber'
+
+Turned off, because it is more useful to have a sense of absolute progress through the results list than to have the ability to jump to nearby results (especially seeing as the most common operations are moving to the next or previous file, which are both handled nicely by <strong>`:cnf`</strong> and <strong>`:cpf`</strong> respectively).
+
+<p align="right"><a name="ferret-nowrap" href="#user-content-ferret-nowrap"><code>ferret-nowrap</code></a></p>
+'nowrap'
+
+Turned off to avoid ugly wrapping that makes the results list hard to read, and because in search results, the most relevant information is the filename, which is on the left and is usually visible even without wrapping.
+
+<p align="right"><a name="ferret-number" href="#user-content-ferret-number"><code>ferret-number</code></a></p>
+'number'
+
+Turned on to give a sense of absolute progress through the results.
+
+<p align="right"><a name="ferret-scrolloff" href="#user-content-ferret-scrolloff"><code>ferret-scrolloff</code></a></p>
+'scrolloff'
+
+Set to 0 because the <strong>`quickfix`</strong> listing is usually small by default, so trying to keep the current line away from the edge of the viewpoint is futile; by definition it is usually near the edge.
+
+<p align="right"><a name="ferret-nocursorline" href="#user-content-ferret-nocursorline"><code>ferret-nocursorline</code></a></p>
+'nocursorline'
+
+Turned off to reduce visual clutter.
+
+To prevent any of these <strong>`quickfix`</strong>-specific overrides from being set up, you can set <strong>`g:FerretQFOptions`</strong> to 0 in your <strong>`.vimrc`</strong>:
+
+```
+let g:FerretQFOptions=0
+```
+
+## Troubleshooting
+
+<p align="right"><a name="ferret-quotes" href="#user-content-ferret-quotes"><code>ferret-quotes</code></a></p>
+### Ferret fails to find patterns containing spaces
+
+As described in the documentation for <strong>[`:Ack`](#user-content-ack)</strong>, the search pattern is passed through as-is to the underlying search command, and no escaping is required other than preceding spaces by a single backslash.
+
+So, to find "foo bar", you would search like:
+
+```
+:Ack foo\ bar
+```
+
+Unescaped spaces in the search are treated as argument separators, so a command like the following means pass the `-w` option through, search for pattern "foo", and limit search to the "bar" directory:
+
+```
+:Ack -w foo bar
+```
+
+Note that including quotes will not do what you intend.
+
+```
+ " Search for '"foo' in the 'bar"' directory:
+ :Ack "foo bar"
+
+ " Search for "'foo' in the "bar'" directory:
+ :Ack 'foo bar'
+```
+
+This approach to escaping is taken in order to make it straightfoward to use powerful Perl-compatible regular expression syntax in an unambiguous way without having to worry about shell escaping rules:
+
+```
+:Ack \blog\((['"]).*?\1\) -i --ignore-dir=src/vendor src dist build
+```
+
+## FAQ
+
+### Why do Ferret commands start with "Ack", "Lack" and so on?
+
+Ferret was originally the thinnest of wrappers (7 lines of code in my <strong>`.vimrc`</strong>) around `ack`. The earliest traces of it can be seen in the initial commit to my dotfiles repo in May, 2009 (https://wt.pe/h).
+
+So, even though Ferret has a new name now and actually prefers `ag` over `ack` when available, I prefer to keep the command names intact and benefit from years of accumulated muscle-memory.
+
+## Related
+
+Just as Ferret aims to improve the multi-file search and replace experience, Loupe does the same for within-file searching:
+
+https://github.com/wincent/loupe
+
+## Website
+
+The official Ferret source code repo is at:
+
+http://git.wincent.com/ferret.git
+
+A mirror exists at:
+
+https://github.com/wincent/ferret
+
+Official releases are listed at:
+
+http://www.vim.org/scripts/script.php?script_id=5220
+
+## License
+
+Copyright 2015-present Greg Hurrell. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+## Development
+
+### Contributing patches
+
+Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests at: https://github.com/wincent/ferret/pulls
+
+### Cutting a new release
+
+At the moment the release process is manual:
+
+- Perform final sanity checks and manual testing
+- Update the <strong>[`ferret-history`](#user-content-ferret-history)</strong> section of the documentation
+- Verify clean work tree:
+
+```
+git status
+```
+
+- Tag the release:
+
+```
+git tag -s -m "$VERSION release" $VERSION
+```
+
+- Publish the code:
+
+```
+git push origin master --follow-tags
+git push github master --follow-tags
+```
+
+- Produce the release archive:
+
+```
+git archive -o ferret-$VERSION.zip HEAD -- .
+```
+
+- Upload to http://www.vim.org/scripts/script.php?script_id=5220
+
+## Authors
+
+Ferret is written and maintained by Greg Hurrell <greg@hurrell.net>.
+
+The idea for vim-dispatch integration was taken from Miles Sterrett's ack.vim plug-in (https://github.com/mileszs/ack.vim).
+
+Other contributors that have submitted patches include (in alphabetical order):
+
+- Daniel Silva
+- Joe Lencioni
+- Nelo-Thara Wallus
+- Vaibhav Sagar
+
+## History
+
+### 1.2a (16 May 2016)
+
+- Add optional support for running searches asynchronously using Vim's <strong>`+job`</strong> feature (enabled by default in sufficiently recent versions of Vim); see <strong>`g:FerretJob`</strong>, <strong>`:FerretCancelAsync`</strong> and <strong>`:FerretPullAsync`</strong>.
+
+### 1.1.1 (7 March 2016)
+
+- Fix another edge case when searching for patterns containing "#", only manifesting under dispatch.vim.
+
+### 1.1 (7 March 2016)
+
+- Fix edge case when searching for strings of the form "<foo>".
+- Fix edge case when searching for patterns containing "#" and "%".
+- Provide completion for `ag` and `ack` options when using <strong>[`:Ack`](#user-content-ack)</strong> and <strong>[`:Lack`](#user-content-lack)</strong>.
+- Fix display of error messages under dispatch.vim.
+
+### 1.0 (28 December 2015)
+
+- Fix broken <strong>[`:Qargs`](#user-content-qargs)</strong> command (patch from Daniel Silva).
+- Add <strong>`g:FerretQFHandler`</strong> and <strong>`g:FerretLLHandler`</strong> options (patch from Daniel Silva).
+- Make <strong>`<Plug>`</strong> mappings accessible even <strong>`g:FerretMap`</strong> is set to 0.
+- Fix failure to report filename when using `ack` and explicitly scoping search to a single file (patch from Daniel Silva).
+- When using `ag`, report multiple matches per line instead of just the first (patch from Daniel Silva).
+- Improve content and display of error messages.
+
+### 0.3 (24 July 2015)
+
+- Added highlighting of search pattern and related <strong>`g:FerretHlsearch`</strong> option (patch from Nelo-Thara Wallus).
+- Add better error reporting for failed or incorrect searches.
+
+### 0.2 (16 July 2015)
+
+- Added <strong>[`FerretDidWrite`](#user-content-ferretdidwrite)</strong> and <strong>[`FerretWillWrite`](#user-content-ferretwillwrite)</strong> autocommands (patch from Joe Lencioni).
+- Add <strong>[`<Plug>(FerretAcks)`](#user-content-plugferretacks)</strong> mapping (patch from Nelo-Thara Wallus).
+
+### 0.1 (8 July 2015)
+
+- Initial release, extracted from my dotfiles (https://github.com/wincent/wincent).
diff --git a/tests/fixtures/integration/ferret/input/autoload/ferret/private.vim b/tests/fixtures/integration/ferret/input/autoload/ferret/private.vim
new file mode 100644 (file)
index 0000000..758d009
--- /dev/null
@@ -0,0 +1,454 @@
+" Copyright 2015-present Greg Hurrell. All rights reserved.
+" Licensed under the terms of the BSD 2-clause license.
+
+" Remove lines a:first through a:last from the quickfix listing.
+function! s:delete(first, last)
+  let l:list=getqflist()
+  let l:line=a:first
+
+  while l:line >= a:first && l:line <= a:last
+    " Non-dictionary items will be ignored. This effectively deletes the line.
+    let l:list[l:line - 1]=0
+    let l:line=l:line + 1
+  endwhile
+  call setqflist(l:list, 'r')
+
+  " Go to next entry.
+  execute 'cc ' . a:first
+
+  " Move focus back to quickfix listing.
+  execute "normal \<C-W>\<C-P>"
+endfunction
+
+" Returns 1 if we should/can use vim-dispatch.
+function! ferret#private#dispatch() abort
+  ""
+  " @option g:FerretDispatch boolean 1
+  "
+  " Controls whether to use vim-dispatch (and specifically, |:Make|) to run
+  " |:Ack| searches asynchronously, when available. To prevent vim-dispatch from
+  " being used, set to 0:
+  "
+  " ```
+  " let g:FerretDispatch=0
+  " ```
+  let l:dispatch=get(g:, 'FerretDispatch', 1)
+  return l:dispatch && exists(':Make') == 2
+endfunction
+
+" Returns 1 if we can use Vim's built-in async primitives.
+function! ferret#private#async()
+  let l:async=get(g:, 'FerretJob', 1)
+
+  " Nothing special about 1829; it's just the version I am testing with as I
+  " write this.
+  return l:async && has('patch-7-4-1829')
+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:
+"
+" (1) Using `:echomsg`
+"
+"     When not using vim-dispatch, the screen is getting cleared before the
+"     user sees it, even with a pre-emptive `:redraw!` beforehand. Note that
+"     we can get the message to linger on the screen by making it multi-line and
+"     forcing Vim to show a prompt (see `:h hit-enter-prompt`), but this is not
+"     reliable because the number of lines required to force the prompt will
+"     vary by system, depending on the value of `'cmdheight'`.
+"
+"     When using vim-dispatch, anything we output ends up getting swallowed
+"     before the user sees it, because something it is doing is clearing the
+"     screen. This is true no matter how many lines we output.
+"
+" (2) Writing back into the quickfix/location list
+"
+"     This interacts poorly with vim-dispatch. If we write back an error message
+"     and then call `:copen 1`, vim-dispatch ends up closing the listing before
+"     the user sees it.
+"
+" (3) Using `:echoerr`
+"
+"     This works, but presents to the user as an exception (see `:h :echoerr`).
+"
+function! ferret#private#error(message) abort
+  call inputsave()
+  echohl ErrorMsg
+  unsilent call input(a:message . ': press ENTER to continue')
+  echohl NONE
+  call inputrestore()
+  unsilent echo
+  redraw!
+endfunction
+
+" Parses arguments, extracting a search pattern (which is stored in
+" g:ferret_lastsearch) and escaping space-delimited arguments for use by
+" `system()`. A string containing all the escaped arguments is returned.
+function! s:parse(args) abort
+  if exists('g:ferret_lastsearch')
+    unlet g:ferret_lastsearch
+  endif
+
+  let l:expanded_args=[]
+
+  for l:arg in a:args
+    if ferret#private#option(l:arg)
+      " Options get passed through as-is.
+      call add(l:expanded_args, l:arg)
+    elseif exists('g:ferret_lastsearch')
+      let l:file_args=glob(l:arg, 1, 1) " Ignore 'wildignore', return a list.
+      if len(l:file_args)
+        call extend(l:expanded_args, l:file_args)
+      else
+        " Let through to `ag`/`ack`/`grep`, which will throw ENOENT.
+        call add(l:expanded_args, l:arg)
+      endif
+    else
+      " First non-option arg is considered to be search pattern.
+      let g:ferret_lastsearch=l:arg
+      call add(l:expanded_args, l:arg)
+    endif
+  endfor
+
+  if ferret#private#async()
+    return l:expanded_args
+  endif
+
+  let l:each_word_shell_escaped=map(l:expanded_args, 'shellescape(v:val)')
+  let l:joined=join(l:each_word_shell_escaped)
+  return escape(l:joined, '<>#')
+endfunction
+
+function! ferret#private#clearautocmd() abort
+  if has('autocmd')
+    augroup FerretPostQF
+      autocmd!
+    augroup END
+  endif
+endfunction
+
+function! ferret#private#post(type) abort
+  call ferret#private#clearautocmd()
+  let l:lastsearch = get(g:, 'ferret_lastsearch', '')
+  let l:qflist = a:type == 'qf' ? getqflist() : getloclist(0)
+  let l:tip = ' [see `:help ferret-quotes`]'
+  if len(l:qflist) == 0
+    let l:base = 'No results for search pattern `' . l:lastsearch . '`'
+
+    " Search pattern has no spaces and is entirely enclosed in quotes;
+    " eg 'foo' or "bar"
+    if l:lastsearch =~ '\v^([' . "'" . '"])[^ \1]+\1$'
+      call ferret#private#error(l:base . l:tip)
+    else
+      call ferret#private#error(l:base)
+    endif
+  else
+    " Find any "invalid" entries in the list.
+    let l:invalid = filter(copy(l:qflist), 'v:val.valid == 0')
+    if len(l:invalid) == len(l:qflist)
+      " Every item in the list was invalid.
+      redraw!
+      echohl ErrorMsg
+      for l:item in l:invalid
+        unsilent echomsg l:item.text
+      endfor
+      echohl NONE
+
+      let l:base = 'Search for `' . l:lastsearch . '` failed'
+
+      " When using vim-dispatch, the messages printed above get cleared, so the
+      " only way to see them is with `:messages`.
+      let l:suffix = a:type == 'qf' && ferret#private#dispatch() ?
+            \ ' (run `:messages` to see details)' :
+            \ ''
+
+      " If search pattern looks like `'foo` or `"bar`, it means the user
+      " probably tried to search for 'foo bar' or "bar baz" etc.
+      if l:lastsearch =~ '\v^[' . "'" . '"].+[^' . "'" . '"]$'
+        call ferret#private#error(l:base . l:tip . l:suffix)
+      else
+        call ferret#private#error(l:base . l:suffix)
+      endif
+    endif
+  endif
+endfunction
+
+function! ferret#private#ack(...) abort
+  let l:command=s:parse(a:000)
+  call ferret#private#hlsearch()
+
+  if empty(&grepprg)
+    return
+  endif
+
+  if ferret#private#async()
+    call ferret#private#async#search(l:command, 1)
+  elseif ferret#private#dispatch()
+    call ferret#private#dispatch#search(l:command)
+  else
+    call ferret#private#vanilla#search(l:command, 1)
+  endif
+endfunction
+
+function! ferret#private#lack(...) abort
+  let l:command=s:parse(a:000)
+  call ferret#private#hlsearch()
+
+  if empty(&grepprg)
+    return
+  endif
+
+  if ferret#private#async()
+    call ferret#private#async#search(l:command, 0)
+  else
+    call ferret#private#vanilla#search(l:command, 0)
+  endif
+endfunction
+
+function! ferret#private#hlsearch() abort
+  if has('extra_search')
+    ""
+    " @option g:FerretHlsearch boolean
+    "
+    " Controls whether Ferret should attempt to highlight the search pattern
+    " when running |:Ack| or |:Lack|. If left unset, Ferret will respect the
+    " current 'hlsearch' setting. To force highlighting on or off irrespective
+    " of 'hlsearch', set |g:FerretHlsearch| to 1 (on) or 0 (off):
+    "
+    " ```
+    " let g:FerretHlsearch=0
+    " ```
+    let l:hlsearch=get(g:, 'FerretHlsearch', &hlsearch)
+    if l:hlsearch
+      let @/=g:ferret_lastsearch
+      call feedkeys(":let &hlsearch=1 | echo \<CR>", 'n')
+    endif
+  endif
+endfunction
+
+" Run the specified substitution command on all the files in the quickfix list
+" (mnemonic: "Ack substitute").
+"
+" Specifically, the sequence:
+"
+"   :Ack foo
+"   :Acks /foo/bar/
+"
+" is equivalent to:
+"
+"   :Ack foo
+"   :Qargs
+"   :argdo %s/foo/bar/ge | update
+"
+" (Note: there's nothing specific to Ack in this function; it's just named this
+" way for mnemonics, as it will most often be preceded by an :Ack invocation.)
+function! ferret#private#acks(command) abort
+  " Accept any pattern allowed by E146 (crude sanity check).
+  let l:matches = matchlist(a:command, '\v\C^(([^|"\\a-zA-Z0-9]).+\2.*\2)([cgeiI]*)$')
+  if !len(l:matches)
+    call ferret#private#error(
+          \ 'Ferret: Expected a substitution expression (/foo/bar/); got: ' .
+          \ a:command
+          \ )
+    return
+  endif
+
+  " Pass through options `c`, `i`/`I` to `:substitute`.
+  " Add options `e` and `g` if not already present.
+  let l:pattern = l:matches[1]
+  let l:options = l:matches[3]
+  if l:options !~# 'e'
+    let l:options .= 'e'
+  endif
+  if l:options !~# 'g'
+    let l:options .= 'g'
+  endif
+
+  let l:filenames=ferret#private#qargs()
+  if l:filenames ==# ''
+    call ferret#private#error(
+          \ 'Ferret: Quickfix filenames must be present, but there are none ' .
+          \ '(must use :Ack to find files before :Acks can be used)'
+          \ )
+    return
+  endif
+
+  execute 'args' l:filenames
+
+  call ferret#private#autocmd('FerretWillWrite')
+  execute 'argdo' '%s' . l:pattern . l:options . ' | update'
+  call ferret#private#autocmd('FerretDidWrite')
+endfunction
+
+function! ferret#private#autocmd(cmd) abort
+  if v:version > 703 || v:version == 703 && has('patch438')
+    execute 'silent doautocmd <nomodeline> User ' . a:cmd
+  else
+    execute 'silent doautocmd User ' . a:cmd
+  endif
+endfunction
+
+" Split on spaces, but not backslash-escaped spaces.
+function! s:split(str) abort
+  " Regular expression cheatsheet:
+  "
+  "   \%(...\)    Non-capturing subgroup.
+  "   \@<!        Zero-width negative lookbehind (like Perl `(?<!pattern)`).
+  "   \+          + (backslash needed due to Vim's "nomagic").
+  "   \|          + (backslash needed due to Vim's "nomagic").
+  "   \zs         Start match here.
+  "
+  " So, broken down, this means:
+  "
+  " - Split on any space not preceded by...
+  " - a backslash at the start of the string or...
+  " - a backslash preceded by a non-backslash character.
+  " - Keep the separating whitespace at the end of each string
+  "   (allows callers to track position within overall string).
+  "
+  return split(a:str, '\%(\%(\%(^\|[^\\]\)\\\)\@<!\s\)\+\zs')
+endfunction
+
+function! ferret#private#ackcomplete(arglead, cmdline, cursorpos) abort
+  return ferret#private#complete('Ack', a:arglead, a:cmdline, a:cursorpos)
+endfunction
+
+function! ferret#private#lackcomplete(arglead, cmdline, cursorpos) abort
+  return ferret#private#complete('Lack', a:arglead, a:cmdline, a:cursorpos)
+endfunction
+
+if executable('ag')
+  let s:executable='ag'
+elseif executable('ack')
+  let s:executable='ack'
+elseif executable('grep')
+  let s:executable='grep'
+else
+  let s:executable=''
+endif
+
+let s:options = {
+      \   'ack': [
+      \     '--ignore-ack-defaults',
+      \     '--ignore-case',
+      \     '--ignore-dir',
+      \     '--ignore-directory',
+      \     '--invert-match',
+      \     '--known-types',
+      \     '--literal',
+      \     '--no-recurse',
+      \     '--recurse',
+      \     '--sort-files',
+      \     '--type',
+      \     '--word-regexp',
+      \     '-1',
+      \     '-Q',
+      \     '-R',
+      \     '-i',
+      \     '-k',
+      \     '-r',
+      \     '-v',
+      \     '-w',
+      \   ],
+      \   'ag': [
+      \     '--all-types',
+      \     '--all-text',
+      \     '--case-sensitive',
+      \     '--depth',
+      \     '--follow',
+      \     '--ignore',
+      \     '--ignore-case',
+      \     '--ignore-dir',
+      \     '--invert-match',
+      \     '--literal',
+      \     '--max-count',
+      \     '--skip-vcs-ignores',
+      \     '--unrestricted',
+      \     '--word-regexp',
+      \     '-Q',
+      \     '-U',
+      \     '-a',
+      \     '-i',
+      \     '-m',
+      \     '-s',
+      \     '-t',
+      \     '-u',
+      \     '-v',
+      \     '-w'
+      \   ]
+      \ }
+
+" We provide our own custom command completion because the default
+" -complete=file completion will expand special characters in the pattern (like
+" "#") before we get a chance to see them, breaking the search. As a bonus, this
+" means we can provide option completion for `ack` and `ag` options as well.
+function! ferret#private#complete(cmd, arglead, cmdline, cursorpos) abort
+  let l:args=s:split(a:cmdline[:a:cursorpos])
+
+  let l:command_seen=0
+  let l:pattern_seen=0
+  let l:position=0
+
+  for l:arg in l:args
+    let l:position=l:position + len(l:arg)
+    let l:stripped=substitute(l:arg, '\s\+$', '', '')
+
+    if ferret#private#option(l:stripped)
+      if a:cursorpos <= l:position
+        let l:options=get(s:options, s:executable, [])
+        return filter(l:options, 'match(v:val, l:stripped) == 0')
+      endif
+    elseif l:pattern_seen
+      if a:cursorpos <= l:position
+        " Assume this is a filename, and it's the one we're trying to complete.
+        " Do -complete=file style completion.
+        return glob(a:arglead . '*', 1, 1)
+      end
+    elseif l:command_seen
+      " Let the pattern through unaltered.
+      let l:pattern_seen=1
+    elseif l:stripped ==# a:cmd
+      let l:command_seen=1
+    else
+      " Haven't seen command yet, this must be a range or a count.
+      " (Not valid, but nothing we can do about it here).
+    end
+  endfor
+
+  " Didn't get to a filename; nothing to complete.
+  return []
+endfunction
+
+" Returns true (1) if `str` looks like a command-line option.
+function! ferret#private#option(str) abort
+  return a:str =~# '^-'
+endfunction
+
+" Populate the :args list with the filenames currently in the quickfix window.
+function! ferret#private#qargs() abort
+  let l:buffer_numbers={}
+  for l:item in getqflist()
+    let l:buffer_numbers[l:item['bufnr']]=bufname(l:item['bufnr'])
+  endfor
+  return join(map(values(l:buffer_numbers), 'fnameescape(v:val)'))
+endfunction
+
+" Visual mode deletion and `dd` mapping (special case).
+function! ferret#private#qf_delete() range
+  call s:delete(a:firstline, a:lastline)
+endfunction
+
+" Motion-based deletion from quickfix listing.
+function! ferret#private#qf_delete_motion(type, ...)
+  " Save.
+  let l:selection=&selection
+  let &selection='inclusive'
+
+  let l:firstline=line("'[")
+  let l:lastline=line("']")
+  call s:delete(l:firstline, l:lastline)
+
+  " Restore.
+  let &selection=l:selection
+endfunction
diff --git a/tests/fixtures/integration/ferret/input/autoload/ferret/private/async.vim b/tests/fixtures/integration/ferret/input/autoload/ferret/private/async.vim
new file mode 100644 (file)
index 0000000..62405e2
--- /dev/null
@@ -0,0 +1,152 @@
+" Copyright 2015-present Greg Hurrell. All rights reserved.
+" Licensed under the terms of the BSD 2-clause license.
+
+let s:jobs={}
+
+function! s:channel_id(channel)
+  " Coerce to string, pluck out ID number.
+  return matchstr(a:channel, '\d\+')
+endfunction
+
+function! s:info_from_channel(channel)
+  let l:channel_id=s:channel_id(a:channel)
+  if has_key(s:jobs, l:channel_id)
+    return s:jobs[l:channel_id]
+  endif
+endfunction
+
+function! ferret#private#async#search(command, ack) abort
+  call ferret#private#async#cancel()
+  call ferret#private#autocmd('FerretAsyncStart')
+  let l:command_and_args = extend(split(&grepprg), a:command)
+  let l:job=job_start(l:command_and_args, {
+        \   'err_cb': 'ferret#private#async#err_cb',
+        \   'out_cb': 'ferret#private#async#out_cb',
+        \   'close_cb': 'ferret#private#async#close_cb',
+        \   'err_mode': 'raw',
+        \   'out_mode': 'raw'
+        \ })
+  let l:channel=job_getchannel(l:job)
+  let l:channel_id=s:channel_id(l:channel)
+  let s:jobs[l:channel_id]={
+        \   'channel_id': l:channel_id,
+        \   'job': l:job,
+        \   'errors': [],
+        \   'output': [],
+        \   'pending_error': '',
+        \   'pending_output': '',
+        \   'pending_error_length': 0,
+        \   'pending_output_length': 0,
+        \   'ack': a:ack,
+        \   'window': win_getid()
+        \ }
+endfunction
+
+let s:max_line_length=32768
+
+function! ferret#private#async#err_cb(channel, msg)
+  let l:info=s:info_from_channel(a:channel)
+  if type(l:info) == 4
+    let l:start=0
+    while 1
+      let l:idx=match(a:msg, '\n', l:start)
+      if l:idx==-1
+        if l:info.pending_error_length < s:max_line_length
+          let l:rest=strpart(a:msg, l:start)
+          let l:length=strlen(l:rest)
+          let l:info.pending_error.=l:rest
+          let l:info.pending_error_length+=l:length
+        endif
+        break
+      else
+        if l:info.pending_error_length < s:max_line_length
+          let l:info.pending_error.=strpart(a:msg, l:start, l:idx - l:start)
+        endif
+        call add(l:info.errors, l:info.pending_error)
+        let l:info.pending_error=''
+        let l:info.pending_error_length=0
+      endif
+      let l:start=l:idx + 1
+    endwhile
+  endif
+endfunction
+
+function! ferret#private#async#out_cb(channel, msg)
+  let l:info=s:info_from_channel(a:channel)
+  if type(l:info) == 4
+    let l:start=0
+    while 1
+      let l:idx=match(a:msg, '\n', l:start)
+      if l:idx==-1
+        if l:info.pending_output_length < s:max_line_length
+          let l:rest=strpart(a:msg, l:start)
+          let l:length=strlen(l:rest)
+          let l:info.pending_output.=l:rest
+          let l:info.pending_output_length+=l:length
+        endif
+        break
+      else
+        if l:info.pending_output_length < s:max_line_length
+          let l:info.pending_output.=strpart(a:msg, l:start, l:idx - l:start)
+        endif
+        call add(l:info.output, l:info.pending_output)
+        let l:info.pending_output=''
+        let l:info.pending_output_length=0
+      endif
+      let l:start=l:idx + 1
+    endwhile
+  endif
+endfunction
+
+function! ferret#private#async#close_cb(channel) abort
+  " Job may have been canceled with cancel_async. Do nothing in that case.
+  let l:info=s:info_from_channel(a:channel)
+  if type(l:info) == 4
+    call remove(s:jobs, l:info.channel_id)
+    call ferret#private#autocmd('FerretAsyncFinish')
+    if !l:info.ack
+      " If this is a :Lack search, try to focus appropriate window.
+      call win_gotoid(l:info.window)
+    endif
+    call s:finalize_search(l:info.output, l:info.ack)
+    for l:error in l:info.errors
+      unsilent echomsg l:error
+    endfor
+  endif
+endfunction
+
+function! ferret#private#async#pull() abort
+  for l:channel_id in keys(s:jobs)
+    let l:info=s:jobs[l:channel_id]
+    call s:finalize_search(l:info.output, l:info.ack)
+  endfor
+endfunction
+
+function! ferret#private#async#cancel() abort
+  let l:canceled=0
+  for l:channel_id in keys(s:jobs)
+    let l:info=s:jobs[l:channel_id]
+    call job_stop(l:info.job)
+    call remove(s:jobs, l:channel_id)
+    let l:canceled=1
+  endfor
+  if l:canceled
+    call ferret#private#autocmd('FerretAsyncFinish')
+  endif
+endfunction
+
+function! ferret#private#async#debug() abort
+  return s:jobs
+endfunction
+
+function! s:finalize_search(output, ack)
+  if a:ack
+    cexpr a:output
+    execute get(g:, 'FerretQFHandler', 'botright cwindow')
+    call ferret#private#post('qf')
+  else
+    lexpr a:output
+    execute get(g:, 'FerretLLHandler', 'lwindow')
+    call ferret#private#post('location')
+  endif
+endfunction
diff --git a/tests/fixtures/integration/ferret/input/autoload/ferret/private/dispatch.vim b/tests/fixtures/integration/ferret/input/autoload/ferret/private/dispatch.vim
new file mode 100644 (file)
index 0000000..ffad4e7
--- /dev/null
@@ -0,0 +1,24 @@
+" Copyright 2015-present Greg Hurrell. All rights reserved.
+" Licensed under the terms of the BSD 2-clause license.
+
+function! ferret#private#dispatch#search(command) abort
+  if has('autocmd')
+    augroup FerretPostQF
+      autocmd!
+      autocmd QuickfixCmdPost cgetfile call ferret#private#post('qf')
+    augroup END
+  endif
+  let l:original_makeprg=&l:makeprg
+  let l:original_errorformat=&l:errorformat
+  try
+    let &l:makeprg=&grepprg . ' ' . a:command
+    let &l:errorformat=&grepformat
+    echomsg &l:makeprg
+    Make
+  catch
+    call ferret#private#clearautocmd()
+  finally
+    let &l:makeprg=l:original_makeprg
+    let &l:errorformat=l:original_errorformat
+  endtry
+endfunction
diff --git a/tests/fixtures/integration/ferret/input/autoload/ferret/private/vanilla.vim b/tests/fixtures/integration/ferret/input/autoload/ferret/private/vanilla.vim
new file mode 100644 (file)
index 0000000..205f0e8
--- /dev/null
@@ -0,0 +1,19 @@
+" Copyright 2015-present Greg Hurrell. All rights reserved.
+" Licensed under the terms of the BSD 2-clause license.
+
+function! s:finalize_search(output, ack)
+  if a:ack
+    cexpr a:output
+    execute get(g:, 'FerretQFHandler', 'botright cwindow')
+    call ferret#private#post('qf')
+  else
+    lexpr a:output
+    execute get(g:, 'FerretLLHandler', 'lwindow')
+    call ferret#private#post('location')
+  endif
+endfunction
+
+function! ferret#private#vanilla#search(command, ack) abort
+  let l:output=system(&grepprg . ' ' . a:command)
+  call s:finalize_search(l:output, a:ack)
+endfunction
diff --git a/tests/fixtures/integration/ferret/input/doc/.gitignore b/tests/fixtures/integration/ferret/input/doc/.gitignore
new file mode 100644 (file)
index 0000000..6e92f57
--- /dev/null
@@ -0,0 +1 @@
+tags
diff --git a/tests/fixtures/integration/ferret/input/doc/ferret.txt b/tests/fixtures/integration/ferret/input/doc/ferret.txt
new file mode 100644 (file)
index 0000000..42633e4
--- /dev/null
@@ -0,0 +1,569 @@
+*ferret.txt*    Ferret plug-in for Vim      *ferret*
+
+CONTENTS                                                       *ferret-contents*
+
+1. Intro                  |ferret-intro|
+2. Installation           |ferret-installation|
+3. Options                |ferret-options|
+4. Commands               |ferret-commands|
+5. Mappings               |ferret-mappings|
+6. Custom autocommands    |ferret-custom-autocommands|
+7. Overrides              |ferret-overrides|
+8. Troubleshooting        |ferret-troubleshooting|
+9. FAQ                    |ferret-faq|
+10. Related               |ferret-related|
+11. Website               |ferret-website|
+12. License               |ferret-license|
+13. Development           |ferret-development|
+14. Authors               |ferret-authors|
+15. History               |ferret-history|
+
+INTRO                                                             *ferret-intro*
+
+    "ferret (verb)
+    (ferret something out) search tenaciously for and find something: she
+    had the ability to ferret out the facts."
+
+
+                                                               *ferret-features*
+Ferret improves Vim's multi-file search in four ways:
+
+1. Powerful multi-file search ~
+
+Ferret provides an |:Ack| command for searching across multiple files using
+The Silver Searcher (https://github.com/ggreer/the_silver_searcher), Ack
+(http://beyondgrep.com/), or Grep (http://www.gnu.org/software/grep/).
+Support for passing options through to the underlying search command exists,
+along with the ability to use full regular expression syntax without doing
+special escaping.
+
+Shortcut mappings are provided to start an |:Ack| search (<leader>a) or to
+search for the word currently under the cursor (<leader>s).
+
+Results are normally displayed in the |quickfix| window, but Ferret also
+provides a |:Lack| command that behaves like |:Ack| but uses the |location-list|
+instead, and a <leader>l mapping as a shortcut to |:Lack|.
+
+Finally, Ferret offers integration with dispatch.vim
+(https://github.com/tpope/vim-dispatch), which enables asynchronous
+searching despite the fact that Vim itself is single-threaded.
+
+2. Streamlined multi-file replace ~
+
+The companion to |:Ack| is |:Acks| (mnemonic: "Ack substitute", accessible via
+shortcut <leader>r), which allows you to run a multi-file replace across all
+the files placed in the |quickfix| window by a previous invocation of |:Ack|.
+
+3. Quickfix listing enhancements ~
+
+The |quickfix| listing itself is enhanced with settings to improve its
+usability, and natural mappings that allow quick removal of items from the
+list (for example, you can reduce clutter in the listing by removing lines
+that you don't intend to make changes to).
+
+Additionally, Vim's |:cn|, |:cp|, |:cnf| and |:cpf| commands are tweaked to make it
+easier to immediately identify matches by centering them within the viewport.
+
+4. Easy operations on files in the quickfix listing ~
+
+Finally, Ferret provides a |:Qargs| command that puts the files currently in
+the |quickfix| listing into the |:args| list, where they can be operated on in
+bulk via the |:argdo| command. This is what's used under the covers by |:Acks|
+to do its work.
+
+INSTALLATION                                               *ferret-installation*
+
+To install Ferret, use your plug-in management system of choice.
+
+If you don't have a "plug-in management system of choice", I recommend
+Pathogen (https://github.com/tpope/vim-pathogen) due to its simplicity and
+robustness. Assuming that you have Pathogen installed and configured, and
+that you want to install Ferret into `~/.vim/bundle`, you can do so with:
+>
+    git clone https://github.com/wincent/ferret.git ~/.vim/bundle/ferret
+<
+Alternatively, if you use a Git submodule for each Vim plug-in, you could do
+the following after `cd`-ing into the top-level of your Git superproject:
+>
+    git submodule add https://github.com/wincent/ferret.git ~/vim/bundle/ferret
+    git submodule init
+<
+To generate help tags under Pathogen, you can do so from inside Vim with:
+>
+    :call pathogen#helptags()
+<
+OPTIONS                                                         *ferret-options*
+
+COMMANDS                                                       *ferret-commands*
+
+:Ack {pattern} {options}                                                  *:Ack*
+
+Searches for {pattern} in all the files under the current directory (see
+|:pwd|), unless otherwise overridden via {options}, and displays the results
+in the |quickfix| listing.
+
+`ag` (The Silver Searcher) will be used preferentially if present on the
+system, because it is faster, falling back to `ack` and then `grep` as needed.
+
+If dispatch.vim is installed the search process will run asynchronously via
+the |:Make| command, otherwise it will be run synchronously via |:cexpr|.
+Asynchronous searches are preferred because they do not block, despite the
+fact that Vim itself is single threaded. The |g:FerretDispatch| option can be
+used to prevent the use of dispatch.vim.
+
+The {pattern} is passed through as-is to the underlying search program, and
+no escaping is required other than preceding spaces by a single backslash.
+For example, to search for "\bfoo[0-9]{2} bar\b" (ie. using `ag`'s Perl-style
+regular expression syntax), you could do:
+>
+    :Ack \bfoo[0-9]{2}\ bar\b
+<
+Likewise, {options} are passed through. In this example, we pass the `-w`
+option (to search on word boundaries), and scope the search to the "foo" and
+"bar" subdirectories: >
+>
+    :Ack -w something foo bar
+<
+As a convenience <leader>a is set-up (|<Plug>(FerretAck)|) as a shortcut to
+enter |Cmdline-mode| with `:Ack` inserted on the |Cmdline|. Likewise <leader>s
+(|<Plug>(FerretAckWord)|) is a shortcut for running |:Ack| with the word
+currently under the cursor.
+
+:Lack {pattern} {options}                                                *:Lack*
+
+Just like |:Ack|, but instead of using the |quickfix| listing, which is global
+across an entire Vim instance, it uses the |location-list|, which is a
+per-window construct.
+
+Note that |:Lack| always runs synchronously via |:cexpr|, because dispatch.vim
+doesn't currently support the |location-list|.
+
+:Acks /{pattern}/{replacement}/                                          *:Acks*
+
+Takes all of the files currently in the |quickfix| listing and performs a
+substitution of all instances of {pattern} (a standard Vim search |pattern|)
+by {replacement}.
+
+A typical sequence consists of an |:Ack| invocation to populate the |quickfix|
+listing and then |:Acks| (mnemonic: "Ack substitute") to perform replacements.
+For example, to replace "foo" with "bar" across all files in the current
+directory:
+>
+    :Ack foo
+    :Acks /foo/bar/
+<
+:Qargs                                                                  *:Qargs*
+
+This is a utility function that is used by the |:Acks| command but is also
+generally useful enough to warrant being exposed publicly.
+
+It takes the files currently in the |quickfix| listing and sets them as |:args|
+so that they can be operated on en masse via the |:argdo| command.
+
+MAPPINGS                                                       *ferret-mappings*
+
+Circumstances where mappings do not get set up ~
+
+Note that Ferret will not try to set up the <leader> mappings if any of the
+following are true:
+
+- A mapping for already exists.
+- An alternative mapping for the same functionality has already been set up
+  from a |.vimrc|.
+- The mapping has been suppressed by setting |g:FerretMap| to 1 in your |.vimrc|.
+
+Mappings specific to the quickfix window ~
+
+Additionally, Ferret will set up special mappings in |quickfix| listings,
+unless prevented from doing so by |g:FerretQFMap|:
+
+- `d` (|visual-mode|): delete visual selection
+- `dd` (|Normal-mode|): delete current line
+- `d`{motion} (|Normal-mode|): delete range indicated by {motion}
+
+
+                                                             *<Plug>(FerretAck)*
+Ferret maps <leader>a to |<Plug>(FerretAck)|, which triggers the |:Ack| command.
+To use an alternative mapping instead, create a different one in your |.vimrc|
+instead using |:nmap|:
+>
+    " Instead of <leader>a, use <leader>x.
+    nmap <leader>x <Plug>(FerretAck)
+<
+
+                                                            *<Plug>(FerretLack)*
+Ferret maps <leader>l to |<Plug>(FerretLack)|, which triggers the |:Lack|
+command. To use an alternative mapping instead, create a different one in
+your |.vimrc| instead using |:nmap|:
+>
+    " Instead of <leader>l, use <leader>y.
+    nmap <leader>y <Plug>(FerretLack)
+<
+
+                                                         *<Plug>(FerretAckWord)*
+Ferret maps <leader>s (mnemonix: "selection) to |<Plug>(FerretAckWord)|, which
+uses |:Ack| to search for the word currently under the cursor. To use an
+alternative mapping instead, create a different one in your |.vimrc| instead
+using |:nmap|:
+>
+    " Instead of <leader>s, use <leader>z.
+    nmap <leader>z <Plug>(FerretAckWord)
+<
+
+                                                            *<Plug>(FerretAcks)*
+Ferret maps <leader>r (mnemonic: "replace") to |<Plug>(FerretAcks)|, which
+triggers the |:Acks| command and fills the prompt with the last search term
+from Ferret. to use an alternative mapping instead, create a different one
+in your |.vimrc| instead using |:nmap|:
+>
+    " Instead of <leader>r, use <leader>u.
+    nmap <leader>u <Plug>(FerretAcks)
+<
+
+                                                              *g:FerretDispatch*
+|g:FerretDispatch|                                          boolean (default: 1)
+
+Controls whether to use vim-dispatch (and specifically, |:Make|) to run |:Ack|
+searches asynchronously, when available. To prevent vim-dispatch from being
+used, set to 0:
+>
+    let g:FerretDispatch=0
+<
+
+                                                              *g:FerretHlsearch*
+|g:FerretHlsearch|                                       boolean (default: none)
+
+Controls whether Ferret should attempt to highlight the search pattern when
+running |:Ack| or |:Lack|. If left unset, Ferret will respect the current
+'hlsearch' setting. To force highlighting on or off irrespective of
+'hlsearch', set |g:FerretHlsearch| to 1 (on) or 0 (off):
+>
+    let g:FerretHlsearch=0
+<
+
+                                                             *g:FerretQFOptions*
+|g:FerretQFOptions|                                         boolean (default: 1)
+
+Controls whether to set up setting overrides for |quickfix| windows. These are
+various settings, such as |norelativenumber|, |nolist| and |nowrap|, that are
+intended to make the |quickfix| window, which is typically very small relative
+to other windows, more usable.
+
+A full list of overridden settings can be found in |ferret-overrides|.
+
+To prevent the custom settings from being applied, set |g:FerretQFOptions| to
+0:
+>
+    let g:FerretQFOptions=0
+<
+
+                                                                 *g:FerretQFMap*
+|g:FerretQFMap|                                             boolean (default: 1)
+
+Controls whether to set up mappings in the |quickfix| results window for
+deleting results. The mappings include:
+
+- `d` (|visual-mode|): delete visual selection
+- `dd` (|Normal-mode|): delete current line
+- `d`{motion} (|Normal-mode|): delete range indicated by {motion}
+
+To prevent these mappings from being set up, set to 0:
+>
+    let g:FerretQFMap=0
+<
+
+                                                                *g:FerretLoaded*
+|g:FerretLoaded|                                             any (default: none)
+
+To prevent Ferret from being loaded, set |g:FerretLoaded| to any value in your
+|.vimrc|. For example:
+>
+    let g:FerretLoaded=1
+<
+
+                                                                   *g:FerretMap*
+|g:FerretMap|                                               boolean (default: 1)
+
+Controls whether to set up the Ferret mappings, such as |<Plug>(FerretAck)|
+(see |ferret-mappings| for a full list). To prevent any mapping from being
+configured, set to 0:
+>
+    let g:FerretMap=0
+<
+
+                                                            *g:FerretQFCommands*
+|g:FerretQFCommands|                                        boolean (default: 1)
+
+Controls whether to set up custom versions of the |quickfix| commands, |:cn|,
+|:cnf|, |:cp| an |:cpf|. These overrides vertically center the match within the
+viewport on each jump. To prevent the custom versions from being configured,
+set to 0:
+>
+    let g:FerretQFCommands=0
+<
+CUSTOM AUTOCOMMANDS                                 *ferret-custom-autocommands*
+
+
+                                                *FerretDidWrite* *FerretWillWrite*
+For maximum compatibility with other plug-ins, Ferret runs the following
+"User" autocommands before and after running the file writing operations
+during |:Acks|:
+
+- FerretWillWrite
+- FerretDidWrite
+
+For example, to call a pair of custom functions in response to these events,
+you might do:
+>
+    autocmd! User FerretWillWrite
+    autocmd User FerretWillWrite call CustomWillWrite()
+    autocmd! User FerretDidWrite
+    autocmd User FerretDidWrite call CustomDidWrite()
+<
+OVERRIDES                                                     *ferret-overrides*
+
+Ferret overrides the 'grepformat' and 'grepprg' settings, preferentially
+setting `ag`, `ack` or `grep` as the 'grepprg' (in that order) and configuring a
+suitable 'grepformat'.
+
+Additionally, Ferret includes an |ftplugin| for the |quickfix| listing that
+adjusts a number of settings to improve the usability of search results.
+
+
+                                                                 *ferret-nolist*
+'nolist'
+
+Turned off to reduce visual clutter in the search results, and because
+'list' is most useful in files that are being actively edited, which is not
+the case for |quickfix| results.
+
+
+                                                       *ferret-norelativenumber*
+'norelativenumber'
+
+Turned off, because it is more useful to have a sense of absolute progress
+through the results list than to have the ability to jump to nearby results
+(especially seeing as the most common operations are moving to the next or
+previous file, which are both handled nicely by |:cnf| and |:cpf| respectively).
+
+
+                                                                 *ferret-nowrap*
+'nowrap'
+
+Turned off to avoid ugly wrapping that makes the results list hard to read,
+and because in search results, the most relevant information is the
+filename, which is on the left and is usually visible even without wrapping.
+
+
+                                                                 *ferret-number*
+'number'
+
+Turned on to give a sense of absolute progress through the results.
+
+
+                                                              *ferret-scrolloff*
+'scrolloff'
+
+Set to 0 because the |quickfix| listing is usually small by default, so trying
+to keep the current line away from the edge of the viewpoint is futile; by
+definition it is usually near the edge.
+
+
+                                                           *ferret-nocursorline*
+'nocursorline'
+
+Turned off to reduce visual clutter.
+
+To prevent any of these |quickfix|-specific overrides from being set up, you
+can set |g:FerretQFOptions| to 0 in your |.vimrc|:
+>
+    let g:FerretQFOptions=0
+<
+TROUBLESHOOTING                                         *ferret-troubleshooting*
+
+
+                                                                 *ferret-quotes*
+Ferret fails to find patterns containing spaces ~
+
+As described in the documentation for |:Ack|, the search pattern is passed
+through as-is to the underlying search command, and no escaping is required
+other than preceding spaces by a single backslash.
+
+So, to find "foo bar", you would search like:
+>
+    :Ack foo\ bar
+<
+Unescaped spaces in the search are treated as argument separators, so a
+command like the following means pass the `-w` option through, search for
+pattern "foo", and limit search to the "bar" directory:
+>
+    :Ack -w foo bar
+<
+Note that including quotes will not do what you intend.
+>
+     " Search for '"foo' in the 'bar"' directory:
+     :Ack "foo bar"
+
+     " Search for "'foo' in the "bar'" directory:
+     :Ack 'foo bar'
+<
+This approach to escaping is taken in order to make it straightfoward to use
+powerful Perl-compatible regular expression syntax in an unambiguous way
+without having to worry about shell escaping rules:
+>
+    :Ack \blog\((['"]).*?\1\) -i --ignore-dir=src/vendor src dist build
+<
+FAQ                                                                 *ferret-faq*
+
+Why do Ferret commands start with "Ack", "Lack" and so on? ~
+
+Ferret was originally the thinnest of wrappers (7 lines of code in my
+|.vimrc|) around `ack`. The earliest traces of it can be seen in the initial
+commit to my dotfiles repo in May, 2009 (https://wt.pe/h).
+
+So, even though Ferret has a new name now and actually prefers `ag` over `ack`
+when available, I prefer to keep the command names intact and benefit from
+years of accumulated muscle-memory.
+
+RELATED                                                         *ferret-related*
+
+Just as Ferret aims to improve the multi-file search and replace experience,
+Loupe does the same for within-file searching:
+
+https://github.com/wincent/loupe
+
+WEBSITE                                                         *ferret-website*
+
+The official Ferret source code repo is at:
+
+http://git.wincent.com/ferret.git
+
+A mirror exists at:
+
+https://github.com/wincent/ferret
+
+Official releases are listed at:
+
+http://www.vim.org/scripts/script.php?script_id=5220
+
+LICENSE                                                         *ferret-license*
+
+Copyright 2015-present Greg Hurrell. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+DEVELOPMENT                                                 *ferret-development*
+
+Contributing patches ~
+
+Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests
+at: https://github.com/wincent/ferret/pulls
+
+Cutting a new release ~
+
+At the moment the release process is manual:
+
+- Perform final sanity checks and manual testing
+- Update the |ferret-history| section of the documentation
+- Verify clean work tree:
+>
+    git status
+<
+- Tag the release:
+>
+    git tag -s -m "$VERSION release" $VERSION
+<
+- Publish the code:
+>
+    git push origin master --follow-tags
+    git push github master --follow-tags
+<
+- Produce the release archive:
+>
+    git archive -o ferret-$VERSION.zip HEAD -- .
+<
+- Upload to http://www.vim.org/scripts/script.php?script_id=5220
+
+AUTHORS                                                         *ferret-authors*
+
+Ferret is written and maintained by Greg Hurrell <greg@hurrell.net>.
+
+The idea for vim-dispatch integration was taken from Miles Sterrett's
+ack.vim plug-in (https://github.com/mileszs/ack.vim).
+
+Other contributors that have submitted patches include (in alphabetical
+order):
+
+- Daniel Silva
+- Joe Lencioni
+- Nelo-Thara Wallus
+- Vaibhav Sagar
+
+HISTORY                                                         *ferret-history*
+
+1.2a (16 May 2016) ~
+
+- Add optional support for running searches asynchronously using Vim's |+job|
+  feature (enabled by default in sufficiently recent versions of Vim); see
+  |g:FerretJob|, |:FerretCancelAsync| and |:FerretPullAsync|.
+
+1.1.1 (7 March 2016) ~
+
+- Fix another edge case when searching for patterns containing "#", only
+  manifesting under dispatch.vim.
+
+1.1 (7 March 2016) ~
+
+- Fix edge case when searching for strings of the form "<foo>".
+- Fix edge case when searching for patterns containing "#" and "%".
+- Provide completion for `ag` and `ack` options when using |:Ack| and |:Lack|.
+- Fix display of error messages under dispatch.vim.
+
+1.0 (28 December 2015) ~
+
+- Fix broken |:Qargs| command (patch from Daniel Silva).
+- Add |g:FerretQFHandler| and |g:FerretLLHandler| options (patch from Daniel
+  Silva).
+- Make |<Plug>| mappings accessible even |g:FerretMap| is set to 0.
+- Fix failure to report filename when using `ack` and explicitly scoping
+  search to a single file (patch from Daniel Silva).
+- When using `ag`, report multiple matches per line instead of just the first
+  (patch from Daniel Silva).
+- Improve content and display of error messages.
+
+0.3 (24 July 2015) ~
+
+- Added highlighting of search pattern and related |g:FerretHlsearch| option
+  (patch from Nelo-Thara Wallus).
+- Add better error reporting for failed or incorrect searches.
+
+0.2 (16 July 2015) ~
+
+- Added |FerretDidWrite| and |FerretWillWrite| autocommands (patch from Joe
+  Lencioni).
+- Add |<Plug>(FerretAcks)| mapping (patch from Nelo-Thara Wallus).
+
+0.1 (8 July 2015) ~
+
+- Initial release, extracted from my dotfiles
+  (https://github.com/wincent/wincent).
diff --git a/tests/fixtures/integration/ferret/input/ftplugin/qf.vim b/tests/fixtures/integration/ferret/input/ftplugin/qf.vim
new file mode 100644 (file)
index 0000000..2d277d9
--- /dev/null
@@ -0,0 +1,64 @@
+" Copyright 2015-present Greg Hurrell. All rights reserved.
+" Licensed under the terms of the BSD 2-clause license.
+
+""
+" @option g:FerretQFOptions boolean 1
+"
+" Controls whether to set up setting overrides for |quickfix| windows. These are
+" various settings, such as |norelativenumber|, |nolist| and |nowrap|, that are
+" intended to make the |quickfix| window, which is typically very small relative
+" to other windows, more usable.
+"
+" A full list of overridden settings can be found in |ferret-overrides|.
+"
+" To prevent the custom settings from being applied, set |g:FerretQFOptions|
+" to 0:
+"
+" ```
+" let g:FerretQFOptions=0
+" ```
+let s:options=get(g:, 'FerretQFOptions', 1)
+if s:options
+  setlocal nolist
+  if exists('+relativenumber')
+    setlocal norelativenumber
+  endif
+  setlocal nowrap
+  setlocal number
+
+  " Want to set scrolloff only for the qf window, but it is a global option.
+  let s:original_scrolloff=&scrolloff
+  set scrolloff=0
+
+  if has('autocmd')
+    augroup FerretQF
+      autocmd!
+      autocmd BufLeave <buffer> execute 'set scrolloff=' . s:original_scrolloff
+      autocmd BufEnter <buffer> set scrolloff=0 | setlocal nocursorline
+    augroup END
+  endif
+endif
+
+""
+" @option g:FerretQFMap boolean 1
+"
+" Controls whether to set up mappings in the |quickfix| results window for
+" deleting results. The mappings include:
+"
+" - `d` (|visual-mode|): delete visual selection
+" - `dd` (|Normal-mode|): delete current line
+" - `d`{motion} (|Normal-mode|): delete range indicated by {motion}
+"
+" To prevent these mappings from being set up, set to 0:
+"
+" ```
+" let g:FerretQFMap=0
+" ```
+let s:map=get(g:, 'FerretQFMap', 1)
+if s:map
+  " Make it easy to remove entries from the quickfix listing.
+  " TODO: distinguish between quickfix and location list
+  nnoremap <buffer> <silent> d :set operatorfunc=ferret#private#qf_delete_motion<CR>g@
+  nnoremap <buffer> <silent> dd :call ferret#private#qf_delete()<CR>
+  vnoremap <buffer> <silent> d :call ferret#private#qf_delete()<CR>
+endif
diff --git a/tests/fixtures/integration/ferret/input/plugin/ferret.vim b/tests/fixtures/integration/ferret/input/plugin/ferret.vim
new file mode 100644 (file)
index 0000000..ff2c7a1
--- /dev/null
@@ -0,0 +1,628 @@
+" Copyright 2015-present Greg Hurrell. All rights reserved.
+" Licensed under the terms of the BSD 2-clause license.
+
+""
+" @plugin ferret Ferret plug-in for Vim
+"
+" # Intro
+"
+" > "ferret (verb)<br />
+" > (ferret something out) search tenaciously for and find something: she had
+" > the ability to ferret out the facts."
+"
+"                                                               *ferret-features*
+" Ferret improves Vim's multi-file search in four ways:
+"
+" ## 1. Powerful multi-file search
+"
+" Ferret provides an |:Ack| command for searching across multiple files using
+" The Silver Searcher (https://github.com/ggreer/the_silver_searcher), Ack
+" (http://beyondgrep.com/), or Grep (http://www.gnu.org/software/grep/). Support
+" for passing options through to the underlying search command exists, along
+" with the ability to use full regular expression syntax without doing special
+" escaping.
+"
+" Shortcut mappings are provided to start an |:Ack| search (<leader>a) or to
+" search for the word currently under the cursor (<leader>s).
+"
+" Results are normally displayed in the |quickfix| window, but Ferret also
+" provides a |:Lack| command that behaves like |:Ack| but uses the
+" |location-list| instead, and a <leader>l mapping as a shortcut to |:Lack|.
+"
+" Finally, Ferret offers integration with dispatch.vim
+" (https://github.com/tpope/vim-dispatch), which enables asynchronous searching
+" despite the fact that Vim itself is single-threaded.
+"
+" ## 2. Streamlined multi-file replace
+"
+" The companion to |:Ack| is |:Acks| (mnemonic: "Ack substitute", accessible via
+" shortcut <leader>r), which allows you to run a multi-file replace across all
+" the files placed in the |quickfix| window by a previous invocation of |:Ack|.
+"
+" ## 3. Quickfix listing enhancements
+"
+" The |quickfix| listing itself is enhanced with settings to improve its
+" usability, and natural mappings that allow quick removal of items from the
+" list (for example, you can reduce clutter in the listing by removing lines
+" that you don't intend to make changes to).
+"
+" Additionally, Vim's |:cn|, |:cp|, |:cnf| and |:cpf| commands are tweaked to
+" make it easier to immediately identify matches by centering them within the
+" viewport.
+"
+" ## 4. Easy operations on files in the quickfix listing
+"
+" Finally, Ferret provides a |:Qargs| command that puts the files currently in
+" the |quickfix| listing into the |:args| list, where they can be operated on in
+" bulk via the |:argdo| command. This is what's used under the covers by |:Acks|
+" to do its work.
+"
+"
+" # Installation
+"
+" To install Ferret, use your plug-in management system of choice.
+"
+" If you don't have a "plug-in management system of choice", I recommend
+" Pathogen (https://github.com/tpope/vim-pathogen) due to its simplicity and
+" robustness. Assuming that you have Pathogen installed and configured, and that
+" you want to install Ferret into `~/.vim/bundle`, you can do so with:
+"
+" ```
+" git clone https://github.com/wincent/ferret.git ~/.vim/bundle/ferret
+" ```
+"
+" Alternatively, if you use a Git submodule for each Vim plug-in, you could do
+" the following after `cd`-ing into the top-level of your Git superproject:
+"
+" ```
+" git submodule add https://github.com/wincent/ferret.git ~/vim/bundle/ferret
+" git submodule init
+" ```
+"
+" To generate help tags under Pathogen, you can do so from inside Vim with:
+"
+" ```
+" :call pathogen#helptags()
+" ```
+"
+" @mappings
+"
+" ## Circumstances where mappings do not get set up
+"
+" Note that Ferret will not try to set up the <leader> mappings if any of the
+" following are true:
+"
+" - A mapping for already exists.
+" - An alternative mapping for the same functionality has already been set up
+"   from a |.vimrc|.
+" - The mapping has been suppressed by setting |g:FerretMap| to 1 in your
+"   |.vimrc|.
+"
+" ## Mappings specific to the quickfix window
+"
+" Additionally, Ferret will set up special mappings in |quickfix| listings,
+" unless prevented from doing so by |g:FerretQFMap|:
+"
+" - `d` (|visual-mode|): delete visual selection
+" - `dd` (|Normal-mode|): delete current line
+" - `d`{motion} (|Normal-mode|): delete range indicated by {motion}
+"
+"
+" @footer
+"
+" # Custom autocommands
+"
+"                                                *FerretWillWrite* *FerretDidWrite*
+" For maximum compatibility with other plug-ins, Ferret runs the following
+" "User" autocommands before and after running the file writing operations
+" during |:Acks|:
+"
+" - FerretWillWrite
+" - FerretDidWrite
+"
+" For example, to call a pair of custom functions in response to these events,
+" you might do:
+"
+" ```
+" autocmd! User FerretWillWrite
+" autocmd User FerretWillWrite call CustomWillWrite()
+" autocmd! User FerretDidWrite
+" autocmd User FerretDidWrite call CustomDidWrite()
+" ```
+"
+"
+" # Overrides
+"
+" Ferret overrides the 'grepformat' and 'grepprg' settings, preferentially
+" setting `ag`, `ack` or `grep` as the 'grepprg' (in that order) and configuring
+" a suitable 'grepformat'.
+"
+" Additionally, Ferret includes an |ftplugin| for the |quickfix| listing that
+" adjusts a number of settings to improve the usability of search results.
+"
+" @indent
+"                                                                 *ferret-nolist*
+"   'nolist'
+"
+"   Turned off to reduce visual clutter in the search results, and because
+"   'list' is most useful in files that are being actively edited, which is not
+"   the case for |quickfix| results.
+"
+"                                                       *ferret-norelativenumber*
+"   'norelativenumber'
+"
+"   Turned off, because it is more useful to have a sense of absolute progress
+"   through the results list than to have the ability to jump to nearby results
+"   (especially seeing as the most common operations are moving to the next or
+"   previous file, which are both handled nicely by |:cnf| and |:cpf|
+"   respectively).
+"
+"                                                                 *ferret-nowrap*
+"   'nowrap'
+"
+"   Turned off to avoid ugly wrapping that makes the results list hard to read,
+"   and because in search results, the most relevant information is the
+"   filename, which is on the left and is usually visible even without wrapping.
+"
+"                                                                 *ferret-number*
+"   'number'
+"
+"   Turned on to give a sense of absolute progress through the results.
+"
+"                                                              *ferret-scrolloff*
+"   'scrolloff'
+"
+"   Set to 0 because the |quickfix| listing is usually small by default, so
+"   trying to keep the current line away from the edge of the viewpoint is
+"   futile; by definition it is usually near the edge.
+"
+"                                                           *ferret-nocursorline*
+"   'nocursorline'
+"
+"   Turned off to reduce visual clutter.
+"
+" @dedent
+"
+" To prevent any of these |quickfix|-specific overrides from being set up, you
+" can set |g:FerretQFOptions| to 0 in your |.vimrc|:
+"
+" ```
+" let g:FerretQFOptions=0
+" ```
+"
+"
+" # Troubleshooting
+"
+"                                                                 *ferret-quotes*
+" ## Ferret fails to find patterns containing spaces
+"
+" As described in the documentation for |:Ack|, the search pattern is passed
+" through as-is to the underlying search command, and no escaping is required
+" other than preceding spaces by a single backslash.
+"
+" So, to find "foo bar", you would search like:
+"
+" ```
+" :Ack foo\ bar
+" ```
+"
+" Unescaped spaces in the search are treated as argument separators, so a
+" command like the following means pass the `-w` option through, search for
+" pattern "foo", and limit search to the "bar" directory:
+"
+" ```
+" :Ack -w foo bar
+" ```
+"
+" Note that including quotes will not do what you intend.
+"
+" ```
+" " Search for '"foo' in the 'bar"' directory:
+" :Ack "foo bar"
+"
+" " Search for "'foo' in the "bar'" directory:
+" :Ack 'foo bar'
+" ```
+"
+" This approach to escaping is taken in order to make it straightfoward to use
+" powerful Perl-compatible regular expression syntax in an unambiguous way
+" without having to worry about shell escaping rules:
+"
+" ```
+" :Ack \blog\((['"]).*?\1\) -i --ignore-dir=src/vendor src dist build
+" ```
+"
+"
+" # FAQ
+"
+" ## Why do Ferret commands start with "Ack", "Lack" and so on?
+"
+" Ferret was originally the thinnest of wrappers (7 lines of code in my
+" |.vimrc|) around `ack`. The earliest traces of it can be seen in the initial
+" commit to my dotfiles repo in May, 2009 (https://wt.pe/h).
+"
+" So, even though Ferret has a new name now and actually prefers `ag` over `ack`
+" when available, I prefer to keep the command names intact and benefit from
+" years of accumulated muscle-memory.
+"
+"
+"
+" # Related
+"
+" Just as Ferret aims to improve the multi-file search and replace experience,
+" Loupe does the same for within-file searching:
+"
+"   https://github.com/wincent/loupe
+"
+"
+" # Website
+"
+" The official Ferret source code repo is at:
+"
+"   http://git.wincent.com/ferret.git
+"
+" A mirror exists at:
+"
+"   https://github.com/wincent/ferret
+"
+" Official releases are listed at:
+"
+"   http://www.vim.org/scripts/script.php?script_id=5220
+"
+"
+" # License
+"
+" Copyright 2015-present Greg Hurrell. All rights reserved.
+"
+" Redistribution and use in source and binary forms, with or without
+" modification, are permitted provided that the following conditions are met:
+"
+" 1. Redistributions of source code must retain the above copyright notice,
+"    this list of conditions and the following disclaimer.
+"
+" 2. Redistributions in binary form must reproduce the above copyright notice,
+"    this list of conditions and the following disclaimer in the documentation
+"    and/or other materials provided with the distribution.
+"
+" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+" POSSIBILITY OF SUCH DAMAGE.
+"
+"
+" # Development
+"
+" ## Contributing patches
+"
+" Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests
+" at: https://github.com/wincent/ferret/pulls
+"
+" ## Cutting a new release
+"
+" At the moment the release process is manual:
+"
+" - Perform final sanity checks and manual testing
+" - Update the |ferret-history| section of the documentation
+" - Verify clean work tree:
+"
+" ```
+" git status
+" ```
+"
+" - Tag the release:
+"
+" ```
+" git tag -s -m "$VERSION release" $VERSION
+" ```
+"
+" - Publish the code:
+"
+" ```
+" git push origin master --follow-tags
+" git push github master --follow-tags
+" ```
+"
+" - Produce the release archive:
+"
+" ```
+" git archive -o ferret-$VERSION.zip HEAD -- .
+" ```
+"
+" - Upload to http://www.vim.org/scripts/script.php?script_id=5220
+"
+"
+" # Authors
+"
+" Ferret is written and maintained by Greg Hurrell <greg@hurrell.net>.
+"
+" The idea for vim-dispatch integration was taken from Miles Sterrett's ack.vim
+" plug-in (https://github.com/mileszs/ack.vim).
+"
+" Other contributors that have submitted patches include (in alphabetical
+" order):
+"
+" - Daniel Silva
+" - Joe Lencioni
+" - Nelo-Thara Wallus
+" - Vaibhav Sagar
+"
+"
+" # History
+"
+" ## 1.2a (16 May 2016)
+"
+" - Add optional support for running searches asynchronously using Vim's |+job|
+"   feature (enabled by default in sufficiently recent versions of Vim); see
+"   |g:FerretJob|, |:FerretCancelAsync| and |:FerretPullAsync|.
+"
+" ## 1.1.1 (7 March 2016)
+"
+" - Fix another edge case when searching for patterns containing "#", only
+"   manifesting under dispatch.vim.
+"
+" ## 1.1 (7 March 2016)
+"
+" - Fix edge case when searching for strings of the form "<foo>".
+" - Fix edge case when searching for patterns containing "#" and "%".
+" - Provide completion for `ag` and `ack` options when using |:Ack| and |:Lack|.
+" - Fix display of error messages under dispatch.vim.
+"
+" ## 1.0 (28 December 2015)
+"
+" - Fix broken |:Qargs| command (patch from Daniel Silva).
+" - Add |g:FerretQFHandler| and |g:FerretLLHandler| options (patch from Daniel
+"   Silva).
+" - Make |<Plug>| mappings accessible even |g:FerretMap| is set to 0.
+" - Fix failure to report filename when using `ack` and explicitly scoping
+"   search to a single file (patch from Daniel Silva).
+" - When using `ag`, report multiple matches per line instead of just the first
+"   (patch from Daniel Silva).
+" - Improve content and display of error messages.
+"
+" ## 0.3 (24 July 2015)
+"
+" - Added highlighting of search pattern and related |g:FerretHlsearch| option
+"   (patch from Nelo-Thara Wallus).
+" - Add better error reporting for failed or incorrect searches.
+"
+" ## 0.2 (16 July 2015)
+"
+" - Added |FerretDidWrite| and |FerretWillWrite| autocommands (patch from Joe
+"   Lencioni).
+" - Add |<Plug>(FerretAcks)| mapping (patch from Nelo-Thara Wallus).
+"
+" ## 0.1 (8 July 2015)
+"
+" - Initial release, extracted from my dotfiles
+"   (https://github.com/wincent/wincent).
+
+""
+" @option g:FerretLoaded any
+"
+" To prevent Ferret from being loaded, set |g:FerretLoaded| to any value in your
+" |.vimrc|. For example:
+"
+" ```
+" let g:FerretLoaded=1
+" ```
+if exists('g:FerretLoaded') || &compatible || v:version < 700
+  finish
+endif
+let g:FerretLoaded = 1
+
+" Temporarily set 'cpoptions' to Vim default as per `:h use-cpo-save`.
+let s:cpoptions = &cpoptions
+set cpoptions&vim
+
+if executable('ag') " The Silver Searcher: faster than ack.
+  let s:ackprg = 'ag --vimgrep'
+elseif executable('ack') " Ack: better than grep.
+  let s:ackprg = 'ack --column --with-filename'
+elseif executable('grep') " Grep: it's just grep.
+  let s:ackprg = &grepprg " default is: grep -n $* /dev/null
+endif
+
+if !empty(s:ackprg)
+  let &grepprg=s:ackprg
+  set grepformat=%f:%l:%c:%m
+endif
+
+if has('autocmd')
+  augroup Ferret
+    autocmd!
+    autocmd QuickFixCmdPost [^l]* nested cwindow
+    autocmd QuickFixCmdPost l* nested lwindow
+  augroup END
+endif
+
+""
+" @command :Ack {pattern} {options}
+"
+" Searches for {pattern} in all the files under the current directory (see
+" |:pwd|), unless otherwise overridden via {options}, and displays the results
+" in the |quickfix| listing.
+"
+" `ag` (The Silver Searcher) will be used preferentially if present on the
+" system, because it is faster, falling back to `ack` and then `grep` as needed.
+"
+" If dispatch.vim is installed the search process will run asynchronously via
+" the |:Make| command, otherwise it will be run synchronously via |:cexpr|.
+" Asynchronous searches are preferred because they do not block, despite the
+" fact that Vim itself is single threaded. The |g:FerretDispatch| option can be
+" used to prevent the use of dispatch.vim.
+"
+" The {pattern} is passed through as-is to the underlying search program, and no
+" escaping is required other than preceding spaces by a single backslash. For
+" example, to search for "\bfoo[0-9]{2} bar\b" (ie. using `ag`'s Perl-style
+" regular expression syntax), you could do:
+"
+" ```
+" :Ack \bfoo[0-9]{2}\ bar\b
+" ```
+"
+" Likewise, {options} are passed through. In this example, we pass the `-w`
+" option (to search on word boundaries), and scope the search to the "foo" and
+" "bar" subdirectories: >
+"
+" ```
+" :Ack -w something foo bar
+" ```
+"
+" As a convenience <leader>a is set-up (|<Plug>(FerretAck)|) as a shortcut to
+" enter |Cmdline-mode| with `:Ack` inserted on the |Cmdline|. Likewise <leader>s
+" (|<Plug>(FerretAckWord)|) is a shortcut for running |:Ack| with the word
+" currently under the cursor.
+command! -nargs=+ -complete=customlist,ferret#private#ackcomplete Ack call ferret#private#ack(<f-args>)
+
+""
+" @command :Lack {pattern} {options}
+"
+" Just like |:Ack|, but instead of using the |quickfix| listing, which is global
+" across an entire Vim instance, it uses the |location-list|, which is a
+" per-window construct.
+"
+" Note that |:Lack| always runs synchronously via |:cexpr|, because dispatch.vim
+" doesn't currently support the |location-list|.
+command! -nargs=+ -complete=customlist,ferret#private#lackcomplete Lack call ferret#private#lack(<f-args>)
+
+""
+" @command :Acks /{pattern}/{replacement}/
+"
+" Takes all of the files currently in the |quickfix| listing and performs a
+" substitution of all instances of {pattern} (a standard Vim search |pattern|)
+" by {replacement}.
+"
+" A typical sequence consists of an |:Ack| invocation to populate the |quickfix|
+" listing and then |:Acks| (mnemonic: "Ack substitute") to perform replacements.
+" For example, to replace "foo" with "bar" across all files in the current
+" directory:
+"
+" ```
+" :Ack foo
+" :Acks /foo/bar/
+" ```
+command! -nargs=1 Acks call ferret#private#acks(<q-args>)
+command! FerretCancelAsync call ferret#private#async#cancel()
+command! FerretPullAsync call ferret#private#async#pull()
+
+nnoremap <Plug>(FerretAck) :Ack<space>
+nnoremap <Plug>(FerretLack) :Lack<space>
+nnoremap <Plug>(FerretAckWord) :Ack <C-r><C-w><CR>
+nnoremap <Plug>(FerretAcks)
+      \ :Acks <c-r>=(exists('g:ferret_lastsearch') ? '/' . g:ferret_lastsearch . '//' : ' ')<CR><Left>
+
+""
+" @option g:FerretMap boolean 1
+"
+" Controls whether to set up the Ferret mappings, such as |<Plug>(FerretAck)|
+" (see |ferret-mappings| for a full list). To prevent any mapping from being
+" configured, set to 0:
+"
+" ```
+" let g:FerretMap=0
+" ```
+let s:map=get(g:, 'FerretMap', 1)
+if s:map
+  if !hasmapto('<Plug>(FerretAck)') && maparg('<leader>a', 'n') ==# ''
+    ""
+    " @mapping <Plug>(FerretAck)
+    "
+    " Ferret maps <leader>a to |<Plug>(FerretAck)|, which triggers the |:Ack|
+    " command. To use an alternative mapping instead, create a different one in
+    " your |.vimrc| instead using |:nmap|:
+    "
+    " ```
+    " " Instead of <leader>a, use <leader>x.
+    " nmap <leader>x <Plug>(FerretAck)
+    " ```
+    nmap <unique> <leader>a <Plug>(FerretAck)
+  endif
+
+  if !hasmapto('<Plug>FerretLack') && maparg('<leader>l', 'n') ==# ''
+    ""
+    " @mapping <Plug>(FerretLack)
+    "
+    " Ferret maps <leader>l to |<Plug>(FerretLack)|, which triggers the |:Lack|
+    " command. To use an alternative mapping instead, create a different one in
+    " your |.vimrc| instead using |:nmap|:
+    "
+    " ```
+    " " Instead of <leader>l, use <leader>y.
+    " nmap <leader>y <Plug>(FerretLack)
+    " ```
+    nmap <unique> <leader>l <Plug>(FerretLack)
+  endif
+
+  if !hasmapto('<Plug>(FerretAckWord)') && maparg('<leader>s', 'n') ==# ''
+    ""
+    " @mapping <Plug>(FerretAckWord)
+    "
+    " Ferret maps <leader>s (mnemonix: "selection) to |<Plug>(FerretAckWord)|,
+    " which uses |:Ack| to search for the word currently under the cursor. To
+    " use an alternative mapping instead, create a different one in your
+    " |.vimrc| instead using |:nmap|:
+    "
+    " ```
+    " " Instead of <leader>s, use <leader>z.
+    " nmap <leader>z <Plug>(FerretAckWord)
+    " ```
+    nmap <unique> <leader>s <Plug>(FerretAckWord)
+  endif
+
+  if !hasmapto('<Plug>(FerretAcks)') && maparg('<leader>r', 'n') ==# ''
+    ""
+    " @mapping <Plug>(FerretAcks)
+    "
+    " Ferret maps <leader>r (mnemonic: "replace") to |<Plug>(FerretAcks)|, which
+    " triggers the |:Acks| command and fills the prompt with the last search
+    " term from Ferret. to use an alternative mapping instead, create a
+    " different one in your |.vimrc| instead using |:nmap|:
+    "
+    " ```
+    " " Instead of <leader>r, use <leader>u.
+    " nmap <leader>u <Plug>(FerretAcks)
+    " ```
+    nmap <unique> <leader>r <Plug>(FerretAcks)
+  endif
+endif
+
+""
+" @command :Qargs
+"
+" This is a utility function that is used by the |:Acks| command but is also
+" generally useful enough to warrant being exposed publicly.
+"
+" It takes the files currently in the |quickfix| listing and sets them as
+" |:args| so that they can be operated on en masse via the |:argdo| command.
+command! -bar Qargs execute 'args' ferret#private#qargs()
+
+""
+" @option g:FerretQFCommands boolean 1
+"
+" Controls whether to set up custom versions of the |quickfix| commands, |:cn|,
+" |:cnf|, |:cp| an |:cpf|. These overrides vertically center the match within
+" the viewport on each jump. To prevent the custom versions from being
+" configured, set to 0:
+"
+" ```
+" let g:FerretQFCommands=0
+" ```
+let s:commands=get(g:, 'FerretQFCommands', 1)
+if s:commands
+  " Keep quickfix result centered, if possible, when jumping from result to result.
+  cabbrev <silent> <expr> cn ((getcmdtype() == ':' && getcmdpos() == 3) ? 'cn <bar> normal zz' : 'cn')
+  cabbrev <silent> <expr> cnf ((getcmdtype() == ':' && getcmdpos() == 4) ? 'cnf <bar> normal zz' : 'cnf')
+  cabbrev <silent> <expr> cp ((getcmdtype() == ':' && getcmdpos() == 3) ? 'cp <bar> normal zz' : 'cp')
+  cabbrev <silent> <expr> cpf ((getcmdtype() == ':' && getcmdpos() == 4) ? 'cpf <bar> normal zz' : 'cpf')
+endif
+
+" Restore 'cpoptions' to its former value.
+let &cpoptions = s:cpoptions
+unlet s:cpoptions
diff --git a/tests/fixtures/integration/ferret/input/test.rb b/tests/fixtures/integration/ferret/input/test.rb
new file mode 100755 (executable)
index 0000000..91fd24d
--- /dev/null
@@ -0,0 +1,61 @@
+#!/usr/bin/env ruby
+
+require 'shellwords'
+
+module DSL
+  module Constants
+    Backslash = '\\'
+    Enter = 'Enter'
+    Space = 'Space'
+  end
+
+  class << self
+    def escape(string)
+      Shellwords.shellescape(string)
+    end
+  end
+
+  class Session
+    WAIT_TIMEOUT = 5
+
+    def initialize(name)
+      @name = name
+    end
+
+    def send_keys(*args)
+      escaped = args.map { |arg| DSL.escape(arg) }
+      %x{tmux send-keys -t #{@name} #{escaped.join(' ')}}
+    end
+
+    def wait_for(pattern)
+      buffer = nil
+      start = Time.now
+      while (Time.now - start < WAIT_TIMEOUT)
+        %x{tmux capture-pane -t #{@name}}
+        buffer = %x{tmux show-buffer}
+        %x{tmux delete-buffer}
+        return buffer if buffer =~ pattern
+        sleep 0.25
+      end
+      raise "Failed to find pattern `#{pattern.inspect}` in session `#{@name}`"
+    end
+  end
+
+  def session(name, &block)
+    escaped_name = DSL.escape(name)
+    %x{tmux new-session -d -s #{DSL.escape(escaped_name)}}
+    Session.new(escaped_name).instance_eval(&block)
+    %x{tmux kill-session -t #{escaped_name}}
+  end
+end
+self.extend(DSL)
+Object.instance_eval { include DSL::Constants }
+
+session('ferret-test') do |name|
+  send_keys('vim -u NONE', Enter)
+  send_keys(':set nocompatible', Enter)
+  send_keys(":set rtp+=#{DSL.escape(Dir.pwd)}", Enter)
+  send_keys(':runtime! plugin/ferret.vim', Enter)
+  send_keys(Backslash, 'a', 'usr/bin/env', Backslash, Space, 'ruby', Enter)
+  wait_for(/module DSL/)
+end
diff --git a/tests/fixtures/integration/scalpel/input/.gitignore b/tests/fixtures/integration/scalpel/input/.gitignore
new file mode 100644 (file)
index 0000000..059d4de
--- /dev/null
@@ -0,0 +1 @@
+scalpel-*.zip
diff --git a/tests/fixtures/integration/scalpel/input/LICENSE.md b/tests/fixtures/integration/scalpel/input/LICENSE.md
new file mode 100644 (file)
index 0000000..0638610
--- /dev/null
@@ -0,0 +1,22 @@
+Copyright (c) 2016-present Greg Hurrell
+
+# MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/tests/fixtures/integration/scalpel/input/README.md b/tests/fixtures/integration/scalpel/input/README.md
new file mode 100644 (file)
index 0000000..9b62607
--- /dev/null
@@ -0,0 +1,168 @@
+![Scalpel](https://raw.githubusercontent.com/wincent/scalpel/media/scalpel.png)
+
+## Intro
+
+Scalpel provides a streamlined shortcut for replacing all instances of the word currently under the cursor throughout a file.
+
+In normal mode pressing `<Leader>e` (mnemonic: "edit") will display a prompt pre-populated with the current word and with the cursor placed so that you can start typing the desired replacement:
+
+```
+:Scalpel/\v<foo>//
+```
+
+Press `<Enter>` and Scalpel will prompt to confirm each substitution, starting at the current word (unlike a normal `:%s` command, which starts at the top of the file).
+
+Scalpel works similarly in visual mode, except that it scopes itself to the current visual selection rather than operating over the entire file.
+
+Note that `:Scalpel` just calls through to an underlying `scalpel#substitute` function that does the real work, ultimately calling Vim's own `:substitute`. As such, be aware that whatever changes you make to the command-line prior to pressing `<Enter>` must keep it a valid pattern, or bad things will happen.
+
+The mapping can be suppressed by setting:
+
+```
+let g:ScalpelMap=0
+```
+
+Or overridden:
+
+```
+" Use <Leader>s instead of default <Leader>e:
+nmap <Leader>s <Plug>(Scalpel)
+```
+
+In any case, Scalpel won't overwrite any pre-existing mapping that you might have defined for `<Leader>e`, nor will it create an unnecessary redundant mapping if you've already mapped something to `<Plug>(Scalpel)`.
+
+The `:Scalpel` command name can be overridden if desired. For example, you could shorten it to `:S` with:
+
+```
+let g:ScalpelCommand='S'
+```
+
+Then your Scalpel prompt would look like:
+
+```
+:S/\v<foo>//
+```
+
+The command can be entirely suppressed by setting `g:ScalpelCommand` to an empty string:
+
+```
+let g:ScalpelCommand=''
+```
+
+Finally, all plug-in functionality can be deactivated by setting:
+
+```
+let g:ScalpelLoaded=1
+```
+
+in your `~/.vimrc`.
+
+## Installation
+
+To install Scalpel, use your plug-in management system of choice.
+
+If you don't have a "plug-in management system of choice" and your version of Vim has `packages` support (ie. `+packages` appears in the output of `:version`) then you can simply place the plugin at a location under your `'packpath'` (eg. `~/.vim/pack/bundle/start/scalpel` or similar).
+
+For older versions of Vim, I recommend [Pathogen](https://github.com/tpope/vim-pathogen) due to its simplicity and robustness. Assuming that you have Pathogen installed and configured, and that you want to install Scalpel into `~/.vim/bundle`, you can do so with:
+
+```
+git clone https://github.com/wincent/scalpel.git ~/.vim/bundle/scalpel
+```
+
+Alternatively, if you use a Git submodule for each Vim plug-in, you could do the following after `cd`-ing into the top-level of your Git superproject:
+
+```
+git submodule add https://github.com/wincent/scalpel.git ~/vim/bundle/scalpel
+git submodule init
+```
+
+To generate help tags under Pathogen, you can do so from inside Vim with:
+
+```
+:call pathogen#helptags()
+```
+
+## Website
+
+The official Scalpel source code repo is at:
+
+http://git.wincent.com/scalpel.git
+
+Mirrors exist at:
+
+- https://github.com/wincent/scalpel
+- https://gitlab.com/wincent/scalpel
+- https://bitbucket.org/ghurrell/scalpel
+
+Official releases are listed at:
+
+http://www.vim.org/scripts/script.php?script_id=5381
+
+## License
+
+Copyright (c) 2016-present Greg Hurrell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+## Development
+
+### Contributing patches
+
+Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests at: https://github.com/wincent/scalpel/pulls
+
+### Cutting a new release
+
+At the moment the release process is manual:
+
+- Perform final sanity checks and manual testing.
+- Update the [scalpel-history](#user-content-scalpel-history) section of the documentation.
+- Regenerate the documentation:
+
+```
+docvim README.md doc/scalpel.txt
+```
+
+- Verify clean work tree:
+
+```
+git status
+```
+
+- Tag the release:
+
+```
+git tag -s -m "$VERSION release" $VERSION
+```
+
+- Publish the code:
+
+```
+git push origin master --follow-tags
+git push github master --follow-tags
+```
+
+- Produce the release archive:
+
+```
+git archive -o scalpel-$VERSION.zip HEAD -- .
+```
+
+- Upload to http://www.vim.org/scripts/script.php?script_id=5381
+
+## Authors
+
+Scalpel is written and maintained by Greg Hurrell <greg@hurrell.net>.
+
+## History
+
+### 0.2 (not yet released)
+
+- Support visual mode.
+
+### 0.1 (29 April 2016)
+
+- Initial release.
diff --git a/tests/fixtures/integration/scalpel/input/autoload/scalpel.vim b/tests/fixtures/integration/scalpel/input/autoload/scalpel.vim
new file mode 100644 (file)
index 0000000..f633c99
--- /dev/null
@@ -0,0 +1,88 @@
+" Copyright 2016-present Greg Hurrell. All rights reserved.
+" Licensed under the terms of the MIT license.
+
+function! scalpel#cword(curpos) abort
+  " <cword> Doesn't work usefully in visual mode (always returns first word),
+  " so fake it.
+  let l:line=getline(a:curpos[1])
+  let l:col=a:curpos[2]
+  let l:chars=split(l:line, '\zs')
+  let l:word=[]
+
+  " Look for keyword characters rightwards.
+  for l:char in l:chars[l:col:]
+    if match(l:char, '\k') != -1
+      call add(l:word, l:char)
+    else
+      break
+    endif
+  endfor
+
+  " Look for keyword characters leftwards.
+  for l:char in reverse(l:chars[:l:col - 1])
+    if match(l:char, '\k') != -1
+      call insert(l:word, l:char, 0)
+    else
+      break
+    endif
+  endfor
+
+  return join(l:word, '')
+endfunction
+
+function! scalpel#substitute(patterns, line1, line2, count) abort
+  if a:count == -1
+    " No range supplied, operate on whole buffer.
+    let l:currentline=a:line1
+    let l:firstline=1
+    let l:lastline=line('$')
+  else
+    let l:firstline=a:line1 <= a:line2 ? a:line1 : a:line2
+    let l:lastline=a:line2 >= a:line2 ? a:line2 : a:line1
+    let l:currentline=l:firstline
+  endif
+  if match(a:patterns, '\v^/[^/]*/[^/]*/$') != 0
+    echomsg 'Invalid patterns: ' . a:patterns
+    echomsg 'Expected patterns of the form "/foo/bar/".'
+    return
+  endif
+  if getregtype('s') != ''
+    let l:register=getreg('s')
+  endif
+  normal! qs
+  redir => l:replacements
+  try
+    execute l:currentline . ',' . l:lastline . 's' . a:patterns . 'gce#'
+  catch /^Vim:Interrupt$/
+    return
+  finally
+    normal! q
+    let l:transcript=getreg('s')
+    if exists('l:register')
+      call setreg('s', l:register)
+    endif
+  endtry
+  redir END
+  if len(l:replacements) > 0
+    " At least one instance of pattern was found.
+    let l:last=strpart(l:transcript, len(l:transcript) - 1)
+    if l:last ==# 'l' || l:last ==# 'q' || l:last ==# '\e'
+      " User bailed.
+      return
+    elseif l:last ==# 'a'
+      " Loop around to top of range/file and continue.
+      " Avoid unwanted "Backwards range given, OK to swap (y/n)?" messages.
+      if l:currentline > l:firstline
+        " Drop c flag.
+        execute l:firstline . ',' . l:currentline . '-&gce'
+      endif
+     return
+    endif
+  endif
+
+  " Loop around to top of range/file and continue.
+  " Avoid unwanted "Backwards range given, OK to swap (y/n)?" messages.
+  if l:currentline > l:firstline
+    execute l:firstline . ',' . l:currentline . '-&gce'
+  endif
+endfunction
diff --git a/tests/fixtures/integration/scalpel/input/doc/.gitignore b/tests/fixtures/integration/scalpel/input/doc/.gitignore
new file mode 100644 (file)
index 0000000..6e92f57
--- /dev/null
@@ -0,0 +1 @@
+tags
diff --git a/tests/fixtures/integration/scalpel/input/doc/scalpel.txt b/tests/fixtures/integration/scalpel/input/doc/scalpel.txt
new file mode 100644 (file)
index 0000000..61b8e9d
--- /dev/null
@@ -0,0 +1,182 @@
+*scalpel.txt*    Scalpel plug-in for Vim      *scalpel*
+
+CONTENTS                                                      *scalpel-contents*
+
+1. Intro            |scalpel-intro|
+2. Installation     |scalpel-installation|
+3. Website          |scalpel-website|
+4. License          |scalpel-license|
+5. Development      |scalpel-development|
+6. Authors          |scalpel-authors|
+7. History          |scalpel-history|
+
+INTRO                                                            *scalpel-intro*
+
+Scalpel provides a streamlined shortcut for replacing all instances of the
+word currently under the cursor throughout a file.
+
+In normal mode pressing `<Leader>e` (mnemonic: "edit") will display a prompt
+pre-populated with the current word and with the cursor placed so that you
+can start typing the desired replacement:
+>
+    :Scalpel/\v<foo>//
+<
+Press `<Enter>` and Scalpel will prompt to confirm each substitution, starting
+at the current word (unlike a normal `:%s` command, which starts at the top of
+the file).
+
+Scalpel works similarly in visual mode, except that it scopes itself to the
+current visual selection rather than operating over the entire file.
+
+Note that `:Scalpel` just calls through to an underlying `scalpel#substitute`
+function that does the real work, ultimately calling Vim's own `:substitute`.
+As such, be aware that whatever changes you make to the command-line prior
+to pressing `<Enter>` must keep it a valid pattern, or bad things will happen.
+
+The mapping can be suppressed by setting:
+>
+    let g:ScalpelMap=0
+<
+Or overridden:
+>
+    " Use <Leader>s instead of default <Leader>e:
+    nmap <Leader>s <Plug>(Scalpel)
+<
+In any case, Scalpel won't overwrite any pre-existing mapping that you might
+have defined for `<Leader>e`, nor will it create an unnecessary redundant
+mapping if you've already mapped something to `<Plug>(Scalpel)`.
+
+The `:Scalpel` command name can be overridden if desired. For example, you
+could shorten it to `:S` with:
+>
+    let g:ScalpelCommand='S'
+<
+Then your Scalpel prompt would look like:
+>
+    :S/\v<foo>//
+<
+The command can be entirely suppressed by setting `g:ScalpelCommand` to an
+empty string:
+>
+    let g:ScalpelCommand=''
+<
+Finally, all plug-in functionality can be deactivated by setting:
+>
+    let g:ScalpelLoaded=1
+<
+in your `~/.vimrc`.
+
+INSTALLATION                                              *scalpel-installation*
+
+To install Scalpel, use your plug-in management system of choice.
+
+If you don't have a "plug-in management system of choice" and your version
+of Vim has `packages` support (ie. `+packages` appears in the output of
+`:version`) then you can simply place the plugin at a location under your
+`'packpath'` (eg. `~/.vim/pack/bundle/start/scalpel` or similar).
+
+For older versions of Vim, I recommend
+[Pathogen](https://github.com/tpope/vim-pathogen) due to its simplicity and
+robustness. Assuming that you have Pathogen installed and configured, and
+that you want to install Scalpel into `~/.vim/bundle`, you can do so with:
+>
+    git clone https://github.com/wincent/scalpel.git ~/.vim/bundle/scalpel
+<
+Alternatively, if you use a Git submodule for each Vim plug-in, you could do
+the following after `cd`-ing into the top-level of your Git superproject:
+>
+    git submodule add https://github.com/wincent/scalpel.git ~/vim/bundle/scalpel
+    git submodule init
+<
+To generate help tags under Pathogen, you can do so from inside Vim with:
+>
+    :call pathogen#helptags()
+<
+WEBSITE                                                        *scalpel-website*
+
+The official Scalpel source code repo is at:
+
+http://git.wincent.com/scalpel.git
+
+Mirrors exist at:
+
+- https://github.com/wincent/scalpel
+- https://gitlab.com/wincent/scalpel
+- https://bitbucket.org/ghurrell/scalpel
+
+Official releases are listed at:
+
+http://www.vim.org/scripts/script.php?script_id=5381
+
+LICENSE                                                        *scalpel-license*
+
+Copyright (c) 2016-present Greg Hurrell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
+
+DEVELOPMENT                                                *scalpel-development*
+
+Contributing patches ~
+
+Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests
+at: https://github.com/wincent/scalpel/pulls
+
+Cutting a new release ~
+
+At the moment the release process is manual:
+
+- Perform final sanity checks and manual testing.
+- Update the [scalpel-history](#user-content-scalpel-history) section of the
+  documentation.
+- Regenerate the documentation:
+>
+    docvim README.md doc/scalpel.txt
+<
+- Verify clean work tree:
+>
+    git status
+<
+- Tag the release:
+>
+    git tag -s -m "$VERSION release" $VERSION
+<
+- Publish the code:
+>
+    git push origin master --follow-tags
+    git push github master --follow-tags
+<
+- Produce the release archive:
+>
+    git archive -o scalpel-$VERSION.zip HEAD -- .
+<
+- Upload to http://www.vim.org/scripts/script.php?script_id=5381
+
+AUTHORS                                                        *scalpel-authors*
+
+Scalpel is written and maintained by Greg Hurrell <greg@hurrell.net>.
+
+HISTORY                                                        *scalpel-history*
+
+0.2 (not yet released) ~
+
+- Support visual mode.
+
+0.1 (29 April 2016) ~
+
+- Initial release.
diff --git a/tests/fixtures/integration/scalpel/input/plugin/scalpel.vim b/tests/fixtures/integration/scalpel/input/plugin/scalpel.vim
new file mode 100644 (file)
index 0000000..c84f6ab
--- /dev/null
@@ -0,0 +1,264 @@
+" Copyright 2016-present Greg Hurrell. All rights reserved.
+" Licensed under the terms of the MIT license.
+
+""
+" @plugin scalpel Scalpel plug-in for Vim
+"
+" # Intro
+"
+" Scalpel provides a streamlined shortcut for replacing all instances of the
+" word currently under the cursor throughout a file.
+"
+" In normal mode pressing `<Leader>e` (mnemonic: "edit") will display a prompt
+" pre-populated with the current word and with the cursor placed so that you can
+" start typing the desired replacement:
+"
+"
+" ```
+" :Scalpel/\v<foo>//
+" ```
+"
+" Press `<Enter>` and Scalpel will prompt to confirm each substitution, starting
+" at the current word (unlike a normal `:%s` command, which starts at the top of
+" the file).
+"
+" Scalpel works similarly in visual mode, except that it scopes itself to the
+" current visual selection rather than operating over the entire file.
+"
+" Note that `:Scalpel` just calls through to an underlying `scalpel#substitute`
+" function that does the real work, ultimately calling Vim's own `:substitute`.
+" As such, be aware that whatever changes you make to the command-line prior to
+" pressing `<Enter>` must keep it a valid pattern, or bad things will happen.
+"
+" The mapping can be suppressed by setting:
+"
+" ```
+" let g:ScalpelMap=0
+" ```
+"
+" Or overridden:
+"
+" ```
+" " Use <Leader>s instead of default <Leader>e:
+" nmap <Leader>s <Plug>(Scalpel)
+" ```
+"
+" In any case, Scalpel won't overwrite any pre-existing mapping that you might
+" have defined for `<Leader>e`, nor will it create an unnecessary redundant
+" mapping if you've already mapped something to `<Plug>(Scalpel)`.
+"
+" The `:Scalpel` command name can be overridden if desired. For example, you
+" could shorten it to `:S` with:
+"
+" ```
+" let g:ScalpelCommand='S'
+" ```
+"
+" Then your Scalpel prompt would look like:
+"
+" ```
+" :S/\v<foo>//
+" ```
+"
+" The command can be entirely suppressed by setting `g:ScalpelCommand` to an
+" empty string:
+"
+" ```
+" let g:ScalpelCommand=''
+" ```
+"
+" Finally, all plug-in functionality can be deactivated by setting:
+"
+" ```
+" let g:ScalpelLoaded=1
+" ```
+"
+" in your `~/.vimrc`.
+"
+" # Installation
+"
+" To install Scalpel, use your plug-in management system of choice.
+"
+" If you don't have a "plug-in management system of choice" and your version of
+" Vim has `packages` support (ie. `+packages` appears in the output of
+" `:version`) then you can simply place the plugin at a location under your
+" `'packpath'` (eg. `~/.vim/pack/bundle/start/scalpel` or similar).
+"
+" For older versions of Vim, I recommend
+" [Pathogen](https://github.com/tpope/vim-pathogen) due to its simplicity and
+" robustness. Assuming that you have Pathogen installed and configured, and that
+" you want to install Scalpel into `~/.vim/bundle`, you can do so with:
+"
+" ```
+" git clone https://github.com/wincent/scalpel.git ~/.vim/bundle/scalpel
+" ```
+"
+" Alternatively, if you use a Git submodule for each Vim plug-in, you could do
+" the following after `cd`-ing into the top-level of your Git superproject:
+"
+" ```
+" git submodule add https://github.com/wincent/scalpel.git ~/vim/bundle/scalpel
+" git submodule init
+" ```
+"
+" To generate help tags under Pathogen, you can do so from inside Vim with:
+"
+" ```
+" :call pathogen#helptags()
+" ```
+"
+" # Website
+"
+" The official Scalpel source code repo is at:
+"
+" http://git.wincent.com/scalpel.git
+"
+" Mirrors exist at:
+"
+" - https://github.com/wincent/scalpel
+" - https://gitlab.com/wincent/scalpel
+" - https://bitbucket.org/ghurrell/scalpel
+"
+" Official releases are listed at:
+"
+" http://www.vim.org/scripts/script.php?script_id=5381
+"
+" # License
+"
+" Copyright (c) 2016-present Greg Hurrell
+"
+" Permission is hereby granted, free of charge, to any person obtaining a copy
+" of this software and associated documentation files (the "Software"), to deal
+" in the Software without restriction, including without limitation the rights
+" to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+" copies of the Software, and to permit persons to whom the Software is
+" furnished to do so, subject to the following conditions:
+"
+" The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+"
+" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+" AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+" OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+" SOFTWARE.
+"
+" # Development
+"
+" ## Contributing patches
+"
+" Patches can be sent via mail to greg@hurrell.net, or as GitHub pull requests
+" at: https://github.com/wincent/scalpel/pulls
+"
+" ## Cutting a new release
+"
+" At the moment the release process is manual:
+"
+" - Perform final sanity checks and manual testing.
+" - Update the [scalpel-history](#user-content-scalpel-history) section of the documentation.
+" - Regenerate the documentation:
+"
+" ```
+" docvim README.md doc/scalpel.txt
+" ```
+"
+" - Verify clean work tree:
+"
+" ```
+" git status
+" ```
+"
+" - Tag the release:
+"
+" ```
+" git tag -s -m "$VERSION release" $VERSION
+" ```
+"
+" - Publish the code:
+"
+" ```
+" git push origin master --follow-tags
+" git push github master --follow-tags
+" ```
+"
+" - Produce the release archive:
+"
+" ```
+" git archive -o scalpel-$VERSION.zip HEAD -- .
+" ```
+"
+" - Upload to http://www.vim.org/scripts/script.php?script_id=5381
+"
+" # Authors
+"
+" Scalpel is written and maintained by Greg Hurrell <greg@hurrell.net>.
+"
+" # History
+"
+" ## 0.2 (not yet released)
+"
+" - Support visual mode.
+"
+" ## 0.1 (29 April 2016)
+"
+" - Initial release.
+
+" Provide users with means to prevent loading, as recommended in `:h
+" write-plugin`.
+if exists('g:ScalpelLoaded') || &compatible || v:version < 700
+  finish
+endif
+let g:ScalpelLoaded = 1
+
+" Temporarily set 'cpoptions' to Vim default as per `:h use-cpo-save`.
+let s:cpoptions = &cpoptions
+set cpoptions&vim
+
+let s:command=get(g:, 'ScalpelCommand', 'Scalpel')
+if s:command ==# ''
+  finish
+elseif match(s:command, '\v\C^[A-Z][A-Za-z]*$') == -1
+  echoerr 'g:ScalpelCommand must contain only letters and start with a ' .
+        \ 'capital letter'
+  finish
+endif
+execute 'command! -nargs=1 -range '
+      \ . s:command
+      \ . ' call scalpel#substitute(<q-args>, <line1>, <line2>, <count>)'
+
+" Need to remember last-seen cursor position because `getcurpos()` is not useful
+" in VISUAL modes.
+let s:curpos=getcurpos()
+augroup Scalpel
+  autocmd!
+  autocmd CursorMoved * let s:curpos=getcurpos()
+augroup END
+
+" Local accessor so that we can reference the script-local variable from inside
+" a mapping (as per http://superuser.com/questions/566720).
+function! s:GetCurpos()
+  return s:curpos
+endfunction
+
+" Change all instances of current word (mnemonic: edit).
+execute 'nnoremap <Plug>(Scalpel) :' .
+      \ s:command .
+      \ "/\\v<<C-R>=expand('<cword>')<CR>>//<Left>"
+execute 'vnoremap <Plug>(ScalpelVisual) :' .
+      \ s:command .
+      \ "/\\v<<C-R>=scalpel#cword(<SID>GetCurpos())<CR>>//<Left>"
+
+let s:map=get(g:, 'ScalpelMap', 1)
+if s:map
+  if !hasmapto('<Plug>(Scalpel)') && maparg('<leader>e', 'n') ==# ''
+    nmap <unique> <Leader>e <Plug>(Scalpel)
+  endif
+  if !hasmapto('<Plug>(ScalpelVisual)') && maparg('<leader>e', 'v') ==# ''
+    vmap <unique> <Leader>e <Plug>(ScalpelVisual)
+  endif
+endif
+
+" Restore 'cpoptions' to its former value.
+let &cpoptions = s:cpoptions
+unlet s:cpoptions