- Changed error handling -- VCL failure for unrecoverable errors.
- .compile() is now unnecessary and deprecated.
- Addition of .subroutine() and .check_call().
- Update the REQUIREMENTS and compatibility statements.
- Fix some typos noticed along the way.

.compile() is still legal, but unnecessary and will be deprecated.

Up to now we have emitted sentinel values for this class of errors,
a relic of the time before VCL failure was introduced, when the VMOD
was first developed. This may lead to fatal errors going unnoticed.
These are the sorts of errors that should fail fast in development
and testing, and never make it into production.

We were already using VCL failure for the integer() method, since
there is no sentinel integer.

VCL failure is now invoked for these errors:

- any regex compilation failure

- all out of workspace errors

- compile() or add() called in any VCL subroutine besides vcl_init

- match() called for a set that was not compiled

- failures reported by the RE2 lib for: match(), backref(),
  namedref(), the rewrite operations (sub, suball and extract),
  cost(), quotemeta()

- numeric index reference for a set object (n parameter) that is out
  of range (greater than the number of patterns in the set)

- functions and methods that require a previous successful match
  operation (with information stored in priv_task) when there was no
  prior match, or the previous macth failed.

- use of select=UNIQUE when more than one pattern in a set matched

- numeric (by index) or "associative" (after match) retrieval of an
  object for a set when no such object was saved in the constructor:
  strings, backends, regexen, etc

- any of the following are undefined (NULL): fallbacks; patterns for
  regex functions (which are compiled at runtime); the text and
  rewrite parameters for the rewrite operations; name parameter
  for namedrefs

- also if the named parameter for namedrefs is the empty string

- backref number out of range (greater than the number of backrefs)

- backref or namedref attempted without a prior match

- backref or namedref when never_capture=true in the contructor

- low-level failures reported by RE2 (eg cannot determine the number
  of backref groups). Most of these are possible, since the call
  returns an error status, but I have never seen them happen.

VTC tests have been revised for the new error handling, which changes
quite a bit in this commit.

While we're here, use backend None in the tests where appropriate.
Note that "bad_ip" backends are still necessary to test methods and
functions that retrieve backends (numeric or associative references
for sets).

Error reporting is now done with VCL_fail(), so we get rid of the
errmsg() function, and with it the re2.c source (since that was all
there was in re2.c).

use VRT_Fail() instead

This change should be improved by refactoring error handling

Ref:
https://github.com/varnishcache/varnish-cache/commit/681c11998ec56dc4460a30585210f95a7850ea3b

The rst source has apparently become too large for gitlab web sites
to be able to render it. So we just go with markdown, in the hopes
that gitlab can better cope with it.

It's not an error if you don't have pandoc installed, but then
README will not be kept up to date with the docs in vcc.

Since 2020-06-01, backrefs fail if numbered higher than the highest
backref actually captured- Previously, re2 returned the empty string.

I believe that these tests will now pass for both current and earlier
versions.

configure checks if you have lcov & genhtml; these can be specified
with --with-lcov and/or --with-genhtml.

If they are available, then make coverage does the following:

- make clean, then make check with CC=gcc & CXX=g++, and CFLAGS &&
  CXXFLAGS set so that inputs for gcov/lcov are generated.

- lcov creates the src/coverage subdir and generates a targetfile
  there.

- genhtml generates HTML reports in src/coverage.

This necessitates adding the matchonly() method to the vre2set
interface, which only checks for matches, and does not save the
indices of matching elements. It also requires a length parameter
(since headers in struct http are not null-terminated).

It also requires the return of the configure-time check for whether
the RE2::Set::Match() method can be called with a NULL vector for
the indices.

Also update set.saved(), to enable checking if an integer was saved.

re2 no longer does that since commit
848dfb7e1d7ba641d598cb66f81590f3999a555a.

This should hopefully fix a panic which has to be caused by forgotten
WS_Release() calls and which occurred close to VCL code which handles
re2 sets.

Redacted panic:

Panic at: Fri, 05 Apr 2019 19:15:24 GMT
Assert error in WS_Reserve(), cache/cache_ws.c line 236:
  Condition(ws->r == NULL) not true.
version = varnish-trunk revision af2bad23deb2470533158f9d99ad3f4968b8d231, vrt api = 9.0
ident = Linux,3.13.0-137-generic,x86_64,-junix,-smalloc,-sdefault,-hcritbit,epoll
now = 3999664.335146 (mono), 1554491669.714933 (real)
Backtrace:
  0x43c1bb: /usr/sbin/varnishd() [0x43c1bb]
  0x49e182: /usr/sbin/varnishd(VAS_Fail+0x42) [0x49e182]
  0x45d1ac: /usr/sbin/varnishd() [0x45d1ac]
  0x44d792: /usr/sbin/varnishd(VRT_String+0x22) [0x44d792]
  0x44de66: /usr/sbin/varnishd(VRT_SetHdr+0xf6) [0x44de66]
  ...(redacted for customer proprietary information)

See also https://github.com/varnishcache/varnish-cache/issues/2967
for a general discussion regarding an inconsistency in the WS_Reserve()
interface