chore: update "master" → "main"

Merge branch 'pull/4'

Closes: https://github.com/wincent/pinnacle/pull/4
* pull/4:
  docs: update AUTHORS listing
  fix: explicitly check vim.fn.has() value

docs: update AUTHORS listing

With this delicious invocation:

    cd ~/code/docvim
    ./dist-newstyle/build/x86_64-osx/ghc-8.4.4/docvim-0.3.2.1/x/docvim/build/docvim/docvim \
        -c ~/code/pinnacle \
        -v \
        ~/code/pinnacle/doc/pinnacle.txt ~/code/pinnacle/README.md

fix: explicitly check vim.fn.has() value

docs: fix typo in a code comment

fix: capture/extract highlight without relying on nvim_exec

As noted in the comments, it sometimes returns an empty string for
reasons I don't know. So let's just side-step it anyway.

refactor: drop "silent" from capture_highlight call

This was needed historically, but I thought it might be causing
inconsistent behavior nowadays.

I was seeing errors in Corpus if I activated it too soon after opening
Vim (no errors if I waited though).

    Error detected while processing function <SNR>106_CheckColorScheme:
    E5108: Error executing lua ...g/nvim/pack/bundle/opt/pinnacle/lua/wincent/pinnacle.lua:25: attempt to index local 'original' (a nil value)
    E416: missing equal sign: 0
    E416: missing equal sign: null

(Many of these, but those show the basic patterns.)

Adding some debug info, I could see that the `:hi` command we were
trying to use was returning empty strings for some of the groups:

    {
      "StatusLine:  StatusLine     xxx ctermfg=12 ctermbg=11 guifg=#b8b8b8 guibg=#383838",
      "MatchParen:  MatchParen     xxx ctermbg=8 guibg=#585858",
      "StatusLine:  StatusLine     xxx ctermfg=12 ctermbg=11 guifg=#b8b8b8 guibg=#383838",
      "Comment:     Comment        xxx ctermfg=8 guifg=#585858",
      "DiffText:    DiffText       xxx cterm=bold ctermfg=4 ctermbg=10 gui=bold guifg=#7cafc2 guibg=#282828",
      "ModeMsg:     ModeMsg        xxx cterm=bold ctermfg=2 gui=bold guifg=#a1b56c",
      "StatusLine:  StatusLine     xxx ctermfg=12 ctermbg=11 guifg=#b8b8b8 guibg=#383838",
      "MatchParen:  MatchParen     xxx ctermbg=8 guibg=#585858",
      "StatusLine:  StatusLine     xxx ctermfg=12 ctermbg=11 guifg=#b8b8b8 guibg=#383838",
      "Comment:",
      "DiffText:",
      "ModeMsg:",
      "StatusLine:",
      "PmenuSel:",
      "Underlined:",
      "ModeMsg:"
    }

So, this explains the errors. Our `capture_highlight` call is
occasionally getting an empty string back. Subsequent attempts to match
a pattern in the string fail, leading to a `nil` return on the Lua side
and a `null` coercion on the Vim side. I have no idea why the first few
calls all work fine and subsequent calls, even for groups like `ModeMsg`
that previously worked, do not.

In this commit I drop the `silent` in an effort to make the errors go
away. It doesn't work (we're still getting empty strings), but it does
show that we don't need the silent any more, so let's just go with it
and keep exploring.

refactor!: remove sub_newlines and capture_line from Lua API

Because these are ancient methods that were only added to support
ancient versions of Vim (ie. before `execute()` existed). For context,
see:

- https://github.com/wincent/wincent/commit/3b0b2950cdcb09d23c87f0167c207d8c837cb1b2
- https://github.com/wincent/wincent/commit/386edd17854e609fe9dd9736524798e7057eefe7

Back in the old days, we used to capture the output of `:highlight`
with `:redir`, and it was sensitive to terminal width, which meant that
lines could wrap and wreak havoc. In newer Vim we just use `execute()`
which is width-agnostic, and in Neovim we can be even more direct
and call `nvim_exec()`. ie. instead of going Lua to Vimscript (eg.
`vim.fn.execute`) to turn a string into a command to run, we can go from
Lua directly to running the command.

docs: fix typo in function name

docs: note the addition of the alternative Lua-based API

feat: add Lua implementation

For use inside Neovim. You can replace calls to the autoloaded Vimscript
function with calls to the Lua implementation; they should be
equivalent.

eg. these two are equivalent:

    :call pinnacle#italicize('Comment')
    :lua require'wincent.pinnacle'.italicize('Comment')

fix: don't use trim() without checking first to see if it exists

The stock Vim that comes with macOS High Sierra doesn't have `trim()`.

feat: teach pinnacle#decorate() to accept a comma-separated list

Incidentally, first time I've tried running docvim on this machine, and
I couldn't get any of the old build or install methods working, due to
bit rot:

    git clone ...
    cd docvim
    brew install stack # didn't have stack on this machine
    stack build # build fails
    stack install docvim # install fails
    cabal install docvim # install fails
    cabal v2-build # victory!

After that I could do the actual doc-gen with:

    ./dist-newstyle/build/x86_64-osx/ghc-8.4.4/docvim-0.3.2.1/x/docvim/build/docvim/docvim \
      -c ~/code/pinnacle \
      -v \
      ~/code/pinnacle/doc/pinnacle.txt \
      ~/code/pinnacle/README.md

Prepare for 1.0 release

Avoid potential issues with nested :redir calls by preferring execute()

Remove awkward cast

Rebuild help docs with docvim tweaked to make functions into subheadings

They weren't standing out at all, so this should help.

Ignore local tags file

Add missing function documentation

Pretty thin as far as documentation goes, but better than nothing.

Add pinnacle#dump(), counterpart to pinnacle#highlight()

Oh what fun it is to program in Vimscript. That `filter` call needs to
use string comparison because "any string" == 0 despite the fact that
strings are truthy... The `filter` expression must return 0 or not-0.

Given that pinnacle#dump() will return a prefix key if applicable (term,
cterm or guiterm), make sure pinnacle#highlight() can consume
dictionaries with those keys.

Remove unnecessary s:prefix from

From the `synIDattr` help:

    {mode} can be "gui", "cterm" or "term", to get the attributes
    for that mode. When {mode} is omitted, or an invalid value is
    used, the attributes for the currently active highlighting are
    used (GUI, cterm or term).

So, we don't need the explicit s:prefix here; behavior should be
unchanged.

Merge branch 'pull/3'

Closes: https://github.com/wincent/pinnacle/pull/3
* pull/3:
  doc: Update AUTHORS section
  Add check that termguicolors is also set

doc: Update AUTHORS section

Note that there are some minor changes in the generated output due to
updates to docvim since the last time I generated the documentation.

Add check that termguicolors is also set

When setting the prefix var also make sure that termguicolors is
enabled.

Prep for 0.3.1 release

Use `empty` instead of `==`

Arguably more transparent, and avoids questions about list equality in
VimL compared with other languages (eg. JavaScript, which isn't
referentially transparent, so `[] != []`).

Fix regex capture groups

This is hard to read, but given something like:

  (a)*(b)(c)*

And input like:

  aaaaaabccccc

Vim is going to capture only the last "a" matched by "(a)*".

To make it capture the whole thing we need to turn:

  (a)*

into:

  (%(a)*)

ie. make the inner "(a)" non-capturing.

With Vim's unfortunate escaping, these examples get a bit uglier:

   \(\%(a\)*\)

instead of:

  (%(a)*)

and so on...

This fixes the issue we had where a group like `Underlined`:

  term=underline cterm=underline ctermfg=1 gui=underline guifg=#cc6666

was being emboldened incorrectly as:

  cterm=bold ctermfg=1 gui=bold,underline guifg=#cc6666

Because the following sequence would occur:

1. Search for "gui=...", identifying "ctermfg=..." as the prefix and
   "guifg=..." as the suffix.
2. Throw away "cterm=bold" while reconstructing the new highlight,
   because it was not correctly captured.
3. etc... all bets are off here because we've already thrown away data.

doc: Fix a date in the history section

Prepare for 0.3 release

Fix regex for decorating existing patterns

Was only working with one prefix and one suffix:

  a=b c=d e=f

(finding c=d).

Would fail given:

  a=b c=d e=f g=h

Which means that it would end up creating a dupe rule for "c=d",
potentially, which Vim would then collapse.

Prefer underline over undercurl

Should be equivalent, but the former is more likely to be supported than
the latter according to some docs that I read that I can no longer find.

Add utility functions for constructing highlights piecemeal

Example usage:

```
execute 'highlight User1 ' .
      \ pinnacle#highlight({
      \   'bg': pinnacle#extract_bg('Error'),
      \   'fg': pinnacle#extract_fg('Normal'),
      \   'term': 'bold'
      \ })
```

doc: remove two copy-pasta'd references to docvim

Prepare for 0.2 release

Merge branch 'pull/2'

Closes: https://github.com/wincent/pinnacle/pull/2
* pull/2:
  doc: Update AUTHORS section
  add pinnacle#underline()

doc: Update AUTHORS section

add pinnacle#underline()

Add empty .watchmanconfig

Allows a Watchman instance configured with `enforce_root_files` to watch
this directory even if `root_files` does not contain any of the files in
the directory. (Necessary to get around undesired corporate
`/etc/watchman.json` config.)

Add docvim-generated documentation

Fix the other URL

Provide correct URL to vim.org scripts page

Don't let verbose info mess with operation

`'verbose'` > 0 will lead us to capture output like:

  Comment xxx term=bold,italic cterm=italic ctermfg=8 gui=italic guifg=#65737e
  Last set from ~/code/wincent/roles/dotfiles/files/.vim/after/plugin/color.vim

which will lead to `E416: missing equal sign` errors when we try to use the
captured output.

So, force `'verbose'` to 0 for the duration of the capture.

Ignore release archives

doc: Fix straggling references

To Docvim, and the script number placeholder.

Make best guess at final script number

Initial import

From my dotfiles repo (https://github.com/wincent/wincent), commit
cad99e82bf78497ac4c2b9aee1bc8.