docs: update HISTORY section

Done on my Arch Linux box with:

    docvim \
        -c ~/.config/nvim/pack/bundle/opt/ferret \
        ~/.config/nvim/pack/bundle/opt/ferret/README.md \
        ~/.config/nvim/pack/bundle/opt/ferret/doc/ferret.txt

because, as noted in d8ebfb16262a5175fdd63c97085ebc3116221b8f, I have a
working copy of Docvim stashed away at `~/bin/docvim`.

I first tried to do this on my macOS machine, but seems all my
Stack/Haskell tooling got borked in the move to Monterrey. I did a `brew
reinstall ghc` and `brew reinstall stack` there, but `bin/build` dies
trying to download a version of GHC, as shown by these excerpts:

    host                 = "downloads.haskell.org"
    path                 = "/~ghc/7.10.3/ghc-7.10.3b-x86_64-apple-darwin.tar.bz2"

    503 Backend is unhealthy

So be it, jedi.

fix: don't E684 if quickfix listing is empty

As noted here:

    https://github.com/wincent/ferret/issues/83#issuecomment-1100947870

if the listing is entirely empty and you try to delete something (eg.
with `dd`), we would cause Vim to complain thusly:

    E684: list index out of range: 0

fix: avoid Vimscript footgun

We can't do a truthiness check for a Vimscript dictionary. ie. if the
quickfix listing has items in it, the `filter()` call would die with:

    E728: Using a Dictionary as a Number

So, we can't just do `v:val`. We can't do `v:val != 0` either, because
Vim will say:

    E735: Can only compare Dictionary with Dictionary

A user-hostile programming language, if ever there was one (well,
AppleScript manages to be even more hostile, but still...)

fix: avoid E42 error when deleting last quickfix entry

After deleting the last item in the quickfix listing using Ferret (eg.
with `dd`), we would try to go to the next entry, but given that there
is none, Vim would print:

    E42: No Errors

Repro steps from ticket:

1.  Put one item in quickfix list with:

        :call setqflist([{'text': 'aaa', 'type': 'w'}], 'a')

2.  Open the listing:

        :copen

3.  Delete the entry with `dd`.

Closes: https://github.com/wincent/ferret/issues/83

fix: rg v13.0.0 hang when passing additional options that take arguments

Given a command like:

    :Ack TODO --type go

The logic would see:

- `TODO` and consider it a search term
- `--type` and consider it an option
- `go` and consider it a path

And so fail to append the necessary ".", causing `rg` to fail in Neovim
as described in:

    https://github.com/wincent/ferret/issues/78

One workaround is to explicitly add the ".":

    :Ack TODO --type go .

Another is to force Ferret to see `--type go` as a single option and
not an option-followed-by-a-path with:

    :Ack TODO --type=go

This commit attempts to avoid the need for such workarounds by teaching
Ferret about which commands go with arguments. The solution is by no
means perfect, as we are _not_ implementing a full options parser, but
in my brief testing it at least mitigates the worst symptom of the
problem; namely, the rather unpleasant and inscrutable error:

    Error detected while processing function ferret#private#ack[11]..ferret#private#nvim#search[1]..ferret#pri
    vate#nvim#cancel:
    line    3:
    E474: Invalid argument

Closes: https://github.com/wincent/ferret/issues/82

docs: format leader with backticks

This looks better in both Markdown on GitHub and in Vim's own 'help'
filetype syntax.

docs: fix a minor typo in the docs

feat: add `<Plug>(FerretBack)`, `<Plug>(FerretBlack)`, `<Plug>(FerretQuack)`

These aren't strictly needed because you can make your own mappings
without them, but the fact that they don't exist may cause confusion,
even for me, as seen in the related issue.

Side note: I'm hacking on a Rust rewrite of `docvim` on this machine
(the Arch Linux box), so I needed to switch back to the `haskell` branch
to be able to generate these updates. These are the commands I ran:

    $ bin/build
    $ bin/docvim -v \
               -c ~/.config/nvim/pack/bundle/opt/ferret \
               ~/.config/nvim/pack/bundle/opt/ferret/README.md \
               ~/.config/nvim/pack/bundle/opt/ferret/doc/ferret.txt

To avoid the need to switch branches in the future, going to do this
ghastly hack now:

    $ cp ./.stack-work/install/x86_64-linux-tinfo6/6496d02f2348a6142a8c6ecb42e6438cffcd197b0d048b4873a88b88b39c503e/7.10.3/bin/docvim ~/bin/

Bit worried that might stop working in the future because it is not
statically linked and I'm not confident that I'll be able to build this
package again in the future:

    $ file ./.stack-work/install/x86_64-linux-tinfo6/6496d02f2348a6142a8c6ecb42e6438cffcd197b0d048b4873a88b88b39c503e/7.10.3/bin/docvim
    ./.stack-work/install/x86_64-linux-tinfo6/6496d02f2348a6142a8c6ecb42e6438cffcd197b0d048b4873a88b88b39c503e/7.10.3/bin/docvim: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, BuildID[sha1]=82e97c115cb0a6c4fac8eeab9a03a2e0e2325ed9, for GNU/Linux 4.4.0, stripped

There's also:

    $ file ./.stack-work/dist/x86_64-linux-tinfo6/Cabal-1.22.5.0/build/docvim/docvim
    ./.stack-work/dist/x86_64-linux-tinfo6/Cabal-1.22.5.0/build/docvim/docvim: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, BuildID[sha1]=82e97c115cb0a6c4fac8eeab9a03a2e0e2325ed9, for GNU/Linux 4.4.0, with debug_info, not stripped

(ie. same, with debug symbols)

`ldd` reports these link targets:

    $ ldd ./.stack-work/install/x86_64-linux-tinfo6/6496d02f2348a6142a8c6ecb42e6438cffcd197b0d048b4873a88b88b39c503e/7.10.3/bin/docvim

        linux-vdso.so.1 (0x00007ffe1d7fc000)
        librt.so.1 => /usr/lib/librt.so.1 (0x00007fa5ed433000)
        libutil.so.1 => /usr/lib/libutil.so.1 (0x00007fa5ed42c000)
        libdl.so.2 => /usr/lib/libdl.so.2 (0x00007fa5ed425000)
        libpthread.so.0 => /usr/lib/libpthread.so.0 (0x00007fa5ed404000)
        libgmp.so.10 => /usr/lib/libgmp.so.10 (0x00007fa5ed364000)
        libm.so.6 => /usr/lib/libm.so.6 (0x00007fa5ed220000)
        libc.so.6 => /usr/lib/libc.so.6 (0x00007fa5ed054000)
        /lib64/ld-linux-x86-64.so.2 => /usr/lib64/ld-linux-x86-64.so.2 (0x00007fa5ed460000)

Based on my reading of:

    https://wiki.archlinux.org/title/haskell#Static_linking

it's simply not worth going further down this path. All the proposed
solutions have unpleasant caveats, AFAICT.

Closes: https://github.com/wincent/ferret/issues/79

docs: prepare HISTORY section for further development

Normally I would initialize this lazily when I make the next change, but
doing it eagerly this time because I just installed a pre-push hook for
this repo on this machine that will keep `main` and `master` in sync
whenever I push, and I want to see it working...

docs: prepare 5.1 release notes

fix: make hacked rg output look nicer

As explained in the comment, if we add "." to the `rg` invocation in
order to work around the new behavior, we wind up with ugly results in
the quickfix listing:

    ./a/b/c

instead of:

    a/b/c

My first thought was to just transform these back whenever the hack is
in effect, but I figured I may as well do it any time the user passes
"." or "./" explicitly too (something that users who have run into the
new `rg` behavior may already have muscle memory for doing).

Now, I could apply this to the other search modes (eg. "async" Vim mode
and "vanilla" mode) for consistency, but the truth is I suspect almost
nobody is using those, and if they are, they are probably not in the
habit of appending "." to their searches (because there is not need to).

Related: https://github.com/wincent/ferret/issues/78

fix: work around breakage caused by rg v13.0.0

v13.0.0 broke a number of tools in Neovim, but not in Vim, as described
here:

    https://github.com/BurntSushi/ripgrep/issues/1892

My reading of that is that changes to Neovim will/may be required,
because the `rg` author is right that rg's handling is "technically
correct" and I don't think he's going to change it. Luckily, we don't
have to take sides in that argument because there is a straightforward
enough workaround of always providing a path to search (ie. ".", only if
one isn't already provided by the user).

<tangential-rant>

As I lamented here:

    https://twitter.com/wincent/status/1413536091425198082

installing and building docvim on this machine (in order to include the
update to the "HISTORY" section in the docs) is a frickin' ordeal. It
takes:

1. 5.53s to clone the repo.
2. 3m56s to install GHC.
3. 3m24s to build the project.
4. 1.64s to run the built tool.

Which seems massively out-of-proportion for something that clocks in at
1,380 lines of Haskell according to `sloccount`. On the upside, this is
one of the few tasks I can throw at this Linux box that actually taxes
the machine. 😆

Steps:

    git clone git@git.wincent.com:public/docvim.git

    cd docvim

    bin/docvim \
      -c ~/.vim/pack/bundle/opt/ferret \
      ~/.vim/pack/bundle/opt/ferret/README.md \
      ~/.vim/pack/bundle/opt/ferret/doc/ferret.txt

    # That did't work; need to build first, then retry:
    bin/build

    bin/docvim \
      -c ~/.vim/pack/bundle/opt/ferret \
      ~/.vim/pack/bundle/opt/ferret/README.md \
      ~/.vim/pack/bundle/opt/ferret/doc/ferret.txt

Closes: https://github.com/wincent/ferret/issues/78

docs: document FerretAsyncStart ad FerretAsyncFinish

These have existed since 79fab3c98872feee19bf57e81 ("Provide autocmd
hooks for async start/stop", May 11, 2016) but were never documented.

chore: switch from "master" to "main"

Merge branch 'pull/77'

Closes: https://github.com/wincent/ferret/pull/77
* pull/77:
  docs: update AUTHORS
  docs:fix typo in option documentation (FerrerLazyInit)

docs: update AUTHORS

On a new machine now, so regenerated with:

    git clone https://github.com/wincent/docvim.git
    cd docvim
    pacman -S stack happy
    bin/docvim \
        -c ~/.vim/pack/bundle/opt/ferret \
        ~/.vim/pack/bundle/opt/ferret/README.md \
        ~/.vim/pack/bundle/opt/ferret/doc/ferret.txt

docs:fix typo in option documentation (FerrerLazyInit)

fix: correct failure to detect pre-existing mapping to <Plug>(FerretLack)

docs: try to make the quoting examples even clearer

docs: try to make quoting examples easier to read

Merge branch 'pull/71'

Closes: https://github.com/wincent/ferret/pull/71
* pull/71:
  docs: update AUTHORS section
  docs: small typo in ferret-quotes

docs: update AUTHORS section

docs: small typo in ferret-quotes

feat: make tab completion append trailing slashes to directories

This matches the behavior you would get if you typed:

    :e something<tab>

In a directory with a "something-here" subdirectory.

Closes: https://github.com/wincent/ferret/issues/69

Merge branch 'pull/67'

Closes: https://github.com/wincent/ferret/pull/67
* pull/67:
  docs: update AUTHORS and HISTORY sections
  Use `normal!` instead of `normal`.

docs: update AUTHORS and HISTORY sections

Use `normal!` instead of `normal`.

This avoids remapping the commands by custom user mappings.

feat: add g:FerretAckWordWord (#66)

Closes: https://github.com/wincent/ferret/issues/66

docs: correct "mnemonix" typo

docs: generate image headers using in-development version of docvim

fix: loosen regex that checks for appropriate :Acks argument

Recent changes introduced trailing whitespace here, which is causing the
regex not to match. It seems that neither leading nor trailing
whitespace can cause any harm though, so accept both.

chore: prepare for v5.0 release

fix: make bindings work in location-list as well

feat: Add :Largs and :Lacks

fix: typo in option name

Related: https://github.com/wincent/ferret/issues/62

feat: prefer `:cdo` over `:cfdo`

Closes: https://github.com/wincent/ferret/issues/62

feat!: add g:FerretVeryMagic option

BREAKING CHANGE: the `:Acks` command-line brought up by the
`<Plug>(FerretAcks)` mapping now includes `\v` by default to make
patterns "very magic".

This default can be overridden with the `g:FerretVeryMagic` option.

Closes: https://github.com/wincent/ferret/issues/61

doc: update shortlinks

Avoid capturing bad 'scrolloff' value

I was finding that my 'scrolloff' was getting permanently set to zero in
the following scenario and perhaps in others:

1. Search for something; the quickfix window gets shown and we save the
   current 'scrolloff' value.
2. Move focus to the quickfix window, at which point we set 'scrolloff'
   to 0.
3. Initiate another search; when the new results show up, we save the
   current value of 'scrolloff' (0), overwriting the real value that we
   originally saved.

The simplest fix, then, seems to be this one: only capture the value
the first time we show the window. This means that if you update the
value and we later do a search, we won't capture the new value, but that
seems less likely to happen than the scenario which we're talking about
in this commit, which happens all the time.

Prepare for 4.1 release

Avoid redundant updates to dictionary in ferret#private#qargs()

Add :Quack and :Quack!

As described in the docs, these search like `:Ack`, but scoped to the
quickfix listing.

Fix option autocompletion

Broken since dbf1b19e5da94116fbb479cfb739a.

Fix bad args passed to ferret#private#complete()

As far as I recall, I am supposed to be passing the command name in
here. I think this has been wrong since these lines were added, in
6c21ea462e62fc3022c63580f3bc92.

doc: fix "asynchronoous" typo

Prepare for 4.0.2 release

Make use of `rg --no-config` conditional via feature detection

Addresses:

    https://github.com/wincent/ferret/issues/59

wherein it was reported that only rg version 0.8 and about supports the
`--no-config` switch.

Prep for 4.0.1 release

Handle repeated 'g' flags passed to :Acks

This is amazingly edge casey, but the 'g' flag can be repeated, toggling
the effect each time. So:

  :Acks /foo/bar/gggg

Would actually have the effect of turning off global replacement. As
bf9bffbc21ad3 said:

    The docs for `:Acks` promise that:

    > 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}.

So in order to be true to the promise of replacing "all instances" we
need to make sure that there is only a single 'g' flag.

Prefer long form of commands (eg. :substitute over :s)

Just as a matter of policy, I want script content to be unabbreviated.
User-inputted content can be as brief as you want.

Handle 'gdefault'

The docs for `:Acks` promise that:

> 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}.

So, that means that we should handle `'gdefault'` being set, which would
otherwise invert the meaning of the 'g' flag to `:substitute` and cause
only the first instance on each line to be replaced.

Prepare for 4.0 release

Add missing docs for g:FerretQFHandler

Requires using latest tweaked docvim.

doc: add missing documentation for old options and commands

These have been around for a while, but never documented.

doc: make function references into links

Using latest tweaked docvim build.

doc: make links to options actually links

See: https://github.com/wincent/docvim/issues/40

Regenerated with tweaked docvim build.

doc: improve readability of "Overrides" section

By using headings.

doc: remove excess trailing parens

Avoid leading whitespace in default `ag` arguments list

Add g:FerretExecutableArguments and ferret#get_default_arguments()

Closes: https://github.com/wincent/ferret/pull/46
Closes: https://github.com/wincent/ferret/pull/55

Add --no-config to default rg options

As per:

    https://github.com/wincent/ferret/issues/55#issuecomment-449628588

we don't want a local `.ripgreprc` file to break Ferret.

Don't repeat executable name in s:executables values

In preparation for making it possible to override the options, let's not
mash the executable and the options together.

Merge branch 'pull/58'

Closes: https://github.com/wincent/ferret/pull/58
* pull/58:
  Apply style fixes
  Use the list's 'size' property when available

Apply style fixes

This file was using inconsistent spacing in `let` commands, so make it
consistent.

Use the list's 'size' property when available

It's more efficient to ask the list for its size than to fetch the full
list and pass it to len():

  https://www.reddit.com/r/vim/comments/a5awtc/colder_quickfix_lists_vimways_1124/ebltg37/

This property became available in patch 8.0.1112, so add a fallback to
the previous method when running on older versions.

Merge branch 'pull/57'

Closes: https://github.com/wincent/ferret/pull/57
* pull/57:
  Apply style fixes for consistency
  doc: update AUTHORS and HISTORY
  Set the list's 'title' with last search string

Apply style fixes for consistency

doc: update AUTHORS and HISTORY

Set the list's 'title' with last search string

We create the list using e.g. `cexpr`, which implicitly names the list
after the command that created it. We can provide a more descriptive
title by setting the list's 'title' field (in vim 7.4.2200+) or setting
w:quickfix_title as a fallback (just for the quickfix list).

Avoid 'press ENTER to continue' prompts

I had this hack in place to prevent the error message from getting blown
away before the user sees it, but it is annoying:

    No results for search pattern `foo`: press ENTER to continue

On Vim with 'lambda' and 'timers' support, we can show this instead:

    No results for search pattern `foo`

with no prompt. Strictly speaking, this could have been written without
a lambda expression, but it is tidier this way.

doc: rebuild with tweaked docvim to make commands stand out

Remove stray > from docs

Closes: https://github.com/wincent/ferret/issues/53

doc: Include a more complex example for `:Acks`

Show that backslashes get passed through, match references work, and
that everything is passed along verbatim to Vim's `:substitute` command.

Prepare for 3.0.3 release

Fix for :Lack always opening results in Quickfix window in Neovim

Presumably a copy-pasta bug that happened while preparing 15db82f1.

Thanks to @regedarek for reporting, and @skingtn for noting the
solution.

Closes: https://github.com/wincent/ferret/issues/47

doc: Escape "<leader>" etc in Markdown

So the GitHub Markdown render won't eat them.

Requires docvim with fix for:

    https://github.com/wincent/docvim/issues/39

doc: Fix false claim about mapping suppression

Done from my local docvim install (because I haven't bothered to install
it globally on this machine yet):

```
brew install stack
stack build
bin/docvim ~/code/ferret/doc/ferret.txt ~/code/ferret/README.md -c ~/code/ferret
```

Closes: https://github.com/wincent/ferret/issues/50

Prepare for 3.0.2 release

Fix :Back and :Black

Somehow I managed to break these and didn't test them at all...

Closes: https://github.com/wincent/ferret/issues/48

Prep for 3.0.1 release

Fix failure to handle multiple escaped spaces

Searching for:

    foo\ bar

Would work, but:

    foo\ bar\ baz

Would not, due to a missing "g" flag to `substitute()`.

Closes: https://github.com/wincent/ferret/issues/49

doc: mention ripgrep earlier on in the README

doc: clarify when :Qargs is used

Prepare for 3.0 release

Add g:FerretAutojump

This is a fairly invasive change, so I'll keep my finger poised above
the revert button. For more context, see:

https://github.com/wincent/ferret/issues/21

Notable changes since I last explored this:

- Using `winnr()` to avoid blindly relying on `wincmd p`.
- Switched to `:copen` (from `:cwindow`) to get consistent focusing
  behavior.
- Slight change of `post()` callback ordering so that we can decide
  whether or not to open the listing at all; this allows us to avoid
  showing an empty listing with `:copen`.

Drop support for vim-dispatch

Supporting it is just too painful given the degree of difference between
vim-dispatch and the other environments, especially considering how
vim-dispatch can run with one of any number of underlying strategies.

Given the prevalence of Vim 8 and Neovim nowadays (with async support),
the value is no longer compelling here. So let's just drop it in order
to move faster. Life is too short.

Improve backslash handling

When searching *for* a backslash, our use of `<f-args>` was causing
confusion because of its special behavior with respect to backslashes.
According to `:h <f-args>`:

- Arguments get split on spaces.
- "\ " prevents a space from causing a split.
- "\\" gets replaced with "\".
- "\x" remains unmodified.

So that means searching for "foo\\bar" would turn into a search for
"foo\bar" (which means "foo, word-boundary, ar").

Fix this by replacing `<f-args>` with `<q-args>`, requiring us to do
argument splitting ourselves, using the nastiest regex ever. That one
was fun to write...

Closes: https://github.com/wincent/ferret/issues/41

Prepare for 2.0 release

doc: mention Neovim higher up in the README

Add Neovim support

This is pretty alpha, only lightly tested at this point, and based
mostly on copy-pasta from the Vim 8 async implementation.

Nevertheless, closes: https://github.com/wincent/ferret/issues/44

doc: update shortlink host

Prepare for 1.5 release

doc: add missing words in a sentence

Looks like a had a half-finished sentence in there that I

Add g:FerretMaxResults

Final(?) mitigation for the lockup and lag issues discussed in:

   https://github.com/wincent/ferret/issues/43

Switch a script-local variable to function-local

doc: Fix bad Unicode handling

Looks like I've found a bug in Docvim.

doc: regen docs again

Somehow I didn't get a full update with the last commit. Blew away the
input files and repeated.

doc: Fix Markdown under GitHub's new renderer

Run using the latest version of Docvim (commit 0335d8d) straight out of
the local Docvim repo with:

```
bin/get ferret
bin/test
bin/accept
bin/put ferret
```

doc: add missing heading markup

Conditionally set executable arguments based on support

Decided to add this seeing as I just taught Ferret to pass
`--max-columns` to `rg`, which is a pretty recently added addition to
`rg`. Had to do some lazy-loading shennanigans; hopefully haven't
created any crazy circular dependencies.

Closes: https://github.com/wincent/ferret/issues/32