Update for compatibility with Varnish 6.0.

Also update the compatibility statement for RE2 -- compatible up to and including 2018-04-01. And use $Synopsis manual in the documentation -- we write our own SYNOPSIS.

Update for compatibility with Varnish 6.0.
Also update the compatibility statement for RE2 -- compatible up to and including 2018-04-01. And use $Synopsis manual in the documentation -- we write our own SYNOPSIS.
00dd9e35 · Geoff Simmons · 41b4b679 · 00dd9e35 · 00dd9e35 · 00dd9e35
Commit 00dd9e35 authored Apr 01, 2018 by Geoff Simmons
Hide whitespace changes
Inline Side-by-side

Showing with 248 additions and 117 deletions

README.rst README.rst +236 -111

configure.ac configure.ac +2 -2

vmod_re2.vcc src/vmod_re2.vcc +10 -4

No files found.
--- a/README.rst
+++ b/README.rst
@@ -18,14 +18,17 @@ Varnish Module for access to the Google RE2 regular expression engine

 :Manual section: 3

-SYNOPSIS
-========

-import re2 [from "path"] ;


+
+SYNOPSIS
+========
+
 ::

+  import re2;
+
  # regex object interface
  new OBJECT = re2.regex(STRING pattern [, <regex options>])
  BOOL <obj>.match(STRING)
@@ -300,27 +303,29 @@ turned off.
  just after a newline, and ``$`` also matches just before a newline. Default is
  **false**.

-CONTENTS
-========
-
-* regex(STRING, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
-* BOOL match(STRING, STRING, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
-* STRING backref(INT, STRING)
-* STRING namedref(STRING, STRING)
-* STRING sub(STRING, STRING, STRING, STRING, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
-* STRING suball(STRING, STRING, STRING, STRING, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
-* STRING extract(STRING, STRING, STRING, STRING, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
-* set(ENUM {none,start,both}, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
-* STRING version()

 .. _obj_regex:

-regex
-----
+regex(...)
+----------

 ::

-	new OBJ = regex(STRING pattern, BOOL utf8=0, BOOL posix_syntax=0, BOOL longest_match=0, INT max_mem=8388608, BOOL literal=0, BOOL never_nl=0, BOOL dot_nl=0, BOOL never_capture=0, BOOL case_sensitive=1, BOOL perl_classes=0, BOOL word_boundary=0, BOOL one_line=0)
+   new xregex = regex(
+      STRING pattern,
+      BOOL utf8=0,
+      BOOL posix_syntax=0,
+      BOOL longest_match=0,
+      INT max_mem=8388608,
+      BOOL literal=0,
+      BOOL never_nl=0,
+      BOOL dot_nl=0,
+      BOOL never_capture=0,
+      BOOL case_sensitive=1,
+      BOOL perl_classes=0,
+      BOOL word_boundary=0,
+      BOOL one_line=0
+   )

 Create a regex object from ``pattern`` and the given options (or
 option defaults). If the pattern is invalid, then VCL will fail to
@@ -339,12 +344,8 @@ Example::

 .. _func_regex.match:

-regex.match
-----------
-
-::
-
-	BOOL regex.match(STRING)
+BOOL xregex.match(STRING)
+-------------------------

 Returns ``true`` if and only if the compiled regex matches the given
 string; corresponds to VCL's infix operator ``~``.
@@ -355,14 +356,18 @@ Example::
     call do_on_match;
  }

+
 .. _func_regex.backref:

-regex.backref
-------------
+STRING xregex.backref(INT ref, STRING fallback)
+-----------------------------------------------

 ::

-	STRING regex.backref(INT ref, STRING fallback="**BACKREF METHOD FAILED**")
+      STRING xregex.backref(
+            INT ref,
+            STRING fallback="**BACKREF METHOD FAILED**"
+      )

 Returns the `nth` captured subexpression from the most recent
 successful call of the ``.match()`` method for this object in the same
@@ -419,14 +424,18 @@ Example::
     set req.http.X-Domain = domainmatcher.backref(1);
  }

+
 .. _func_regex.namedref:

-regex.namedref
--------------
+STRING xregex.namedref(STRING name, STRING fallback)
+----------------------------------------------------

 ::

-	STRING regex.namedref(STRING name, STRING fallback="**NAMEDREF METHOD FAILED**")
+      STRING xregex.namedref(
+            STRING name,
+            STRING fallback="**NAMEDREF METHOD FAILED**"
+      )

 Returns the captured subexpression designated by ``name`` from the
 most recent successful call to ``.match()`` in the current context
@@ -473,14 +482,19 @@ Example::
 	}
  }

+
 .. _func_regex.sub:

-regex.sub
---------
+regex.sub(...)
+--------------

 ::

-	STRING regex.sub(STRING text, STRING rewrite, STRING fallback="**SUB METHOD FAILED**")
+      STRING xregex.sub(
+            STRING text,
+            STRING rewrite,
+            STRING fallback="**SUB METHOD FAILED**"
+      )

 If the compiled pattern for this regex object matches ``text``, then
 return the result of replacing the first match in ``text`` with
@@ -510,14 +524,19 @@ Example::
      set req.http.X-Yada = bmatcher.sub(req.http.Host, "d");
  }

+
 .. _func_regex.suball:

-regex.suball
------------
+regex.suball(...)
+-----------------

 ::

-	STRING regex.suball(STRING text, STRING rewrite, STRING fallback="**SUBALL METHOD FAILED**")
+      STRING xregex.suball(
+            STRING text,
+            STRING rewrite,
+            STRING fallback="**SUBALL METHOD FAILED**"
+      )

 Like ``.sub()``, except that all successive non-overlapping matches in
 ``text`` are replaced with ``rewrite``. This method corresponds to VCL
@@ -542,14 +561,19 @@ Example::
      set req.http.X-Yada = bmatcher.suball(req.http.Host, "d");
  }

+
 .. _func_regex.extract:

-regex.extract
-------------
+regex.extract(...)
+------------------

 ::

-	STRING regex.extract(STRING text, STRING rewrite, STRING fallback="**EXTRACT METHOD FAILED**")
+      STRING xregex.extract(
+            STRING text,
+            STRING rewrite,
+            STRING fallback="**EXTRACT METHOD FAILED**"
+      )

 If the compiled pattern for this regex object matches ``text``, then
 return ``rewrite`` with substitutions from the matching portions of
@@ -575,14 +599,33 @@ Example::
 regex functional interface
 ==========================

+
+
+
+
 .. _func_match:

-match
-----
+match(...)
+----------

 ::

-	BOOL match(STRING pattern, STRING subject, BOOL utf8=0, BOOL posix_syntax=0, BOOL longest_match=0, INT max_mem=8388608, BOOL literal=0, BOOL never_nl=0, BOOL dot_nl=0, BOOL never_capture=0, BOOL case_sensitive=1, BOOL perl_classes=0, BOOL word_boundary=0, BOOL one_line=0)
+   BOOL match(
+      STRING pattern,
+      STRING subject,
+      BOOL utf8=0,
+      BOOL posix_syntax=0,
+      BOOL longest_match=0,
+      INT max_mem=8388608,
+      BOOL literal=0,
+      BOOL never_nl=0,
+      BOOL dot_nl=0,
+      BOOL never_capture=0,
+      BOOL case_sensitive=1,
+      BOOL perl_classes=0,
+      BOOL word_boundary=0,
+      BOOL one_line=0
+   )

 Like the ``regex.match()`` method, return ``true`` if ``pattern``
 matches ``subject``, where ``pattern`` is compiled with the given
@@ -598,14 +641,18 @@ Example::
     call do_on_match;
  }

+
 .. _func_backref:

-backref
-------
+STRING backref(INT ref, STRING fallback)
+----------------------------------------

 ::

-	STRING backref(INT ref, STRING fallback="**BACKREF FUNCTION FAILED**")
+   STRING backref(
+      INT ref,
+      STRING fallback="**BACKREF FUNCTION FAILED**"
+   )

 Returns the `nth` captured subexpression from the most recent
 successful call of the ``match()`` function in the current client or
@@ -637,14 +684,18 @@ Example::
     set beresp.http.X-Capture = re2.backref(1);
  }

+
 .. _func_namedref:

-namedref
--------
+STRING namedref(STRING name, STRING fallback)
+---------------------------------------------

 ::

-	STRING namedref(STRING name, STRING fallback="**NAMEDREF FUNCTION FAILED**")
+   STRING namedref(
+      STRING name,
+      STRING fallback="**NAMEDREF FUNCTION FAILED**"
+   )

 Returns the captured subexpression designated by ``name`` from the
 most recent successful call to the ``match()`` function in the current
@@ -671,14 +722,32 @@ Example::
     set beresp.http.X-Capture = re2.namedref("foo");
  }

+
 .. _func_sub:

-sub
---
+sub(...)
+--------

 ::

-	STRING sub(STRING pattern, STRING text, STRING rewrite, STRING fallback="**SUB FUNCTION FAILED**", BOOL utf8=0, BOOL posix_syntax=0, BOOL longest_match=0, INT max_mem=8388608, BOOL literal=0, BOOL never_nl=0, BOOL dot_nl=0, BOOL never_capture=0, BOOL case_sensitive=1, BOOL perl_classes=0, BOOL word_boundary=0, BOOL one_line=0)
+   STRING sub(
+      STRING pattern,
+      STRING text,
+      STRING rewrite,
+      STRING fallback="**SUB FUNCTION FAILED**",
+      BOOL utf8=0,
+      BOOL posix_syntax=0,
+      BOOL longest_match=0,
+      INT max_mem=8388608,
+      BOOL literal=0,
+      BOOL never_nl=0,
+      BOOL dot_nl=0,
+      BOOL never_capture=0,
+      BOOL case_sensitive=1,
+      BOOL perl_classes=0,
+      BOOL word_boundary=0,
+      BOOL one_line=0
+   )

 Compiles ``pattern`` with the given options, and if it matches
 ``text``, then return the result of replacing the first match in
@@ -704,14 +773,32 @@ Example::
  set beresp.http.X-Yada = re2.sub(beresp.http.X-Sub-Letters,
                                   bereq.http.Host, "d");

+
 .. _func_suball:

-suball
------
+suball(...)
+-----------

 ::

-	STRING suball(STRING pattern, STRING text, STRING rewrite, STRING fallback="**SUBALL FUNCTION FAILED**", BOOL utf8=0, BOOL posix_syntax=0, BOOL longest_match=0, INT max_mem=8388608, BOOL literal=0, BOOL never_nl=0, BOOL dot_nl=0, BOOL never_capture=0, BOOL case_sensitive=1, BOOL perl_classes=0, BOOL word_boundary=0, BOOL one_line=0)
+   STRING suball(
+      STRING pattern,
+      STRING text,
+      STRING rewrite,
+      STRING fallback="**SUBALL FUNCTION FAILED**",
+      BOOL utf8=0,
+      BOOL posix_syntax=0,
+      BOOL longest_match=0,
+      INT max_mem=8388608,
+      BOOL literal=0,
+      BOOL never_nl=0,
+      BOOL dot_nl=0,
+      BOOL never_capture=0,
+      BOOL case_sensitive=1,
+      BOOL perl_classes=0,
+      BOOL word_boundary=0,
+      BOOL one_line=0
+   )

 Like the ``sub()`` function, except that all successive
 non-overlapping matches in ``text`` are replace with ``rewrite``.
@@ -727,14 +814,32 @@ Example::
  set beresp.http.X-Yada = re2.suball(beresp.http.X-Sub-Letters,
                                      bereq.http.Host, "d");

+
 .. _func_extract:

-extract
-------
+extract(...)
+------------

 ::

-	STRING extract(STRING pattern, STRING text, STRING rewrite, STRING fallback="**EXTRACT FUNCTION FAILED**", BOOL utf8=0, BOOL posix_syntax=0, BOOL longest_match=0, INT max_mem=8388608, BOOL literal=0, BOOL never_nl=0, BOOL dot_nl=0, BOOL never_capture=0, BOOL case_sensitive=1, BOOL perl_classes=0, BOOL word_boundary=0, BOOL one_line=0)
+   STRING extract(
+      STRING pattern,
+      STRING text,
+      STRING rewrite,
+      STRING fallback="**EXTRACT FUNCTION FAILED**",
+      BOOL utf8=0,
+      BOOL posix_syntax=0,
+      BOOL longest_match=0,
+      INT max_mem=8388608,
+      BOOL literal=0,
+      BOOL never_nl=0,
+      BOOL dot_nl=0,
+      BOOL never_capture=0,
+      BOOL case_sensitive=1,
+      BOOL perl_classes=0,
+      BOOL word_boundary=0,
+      BOOL one_line=0
+   )

 Compiles ``pattern`` with the given options, and if it matches
 ``text``, then return ``rewrite`` with substitutions from the matching
@@ -751,14 +856,28 @@ Example::
  set beresp.http.X-Query = re2.extract(beresp.http.X-Params, bereq.url,
                                        "\1:\2");

+
 .. _obj_set:

-set
---
+set(...)
+--------

 ::

-	new OBJ = set(ENUM {none,start,both} anchor=none, BOOL utf8=0, BOOL posix_syntax=0, BOOL longest_match=0, INT max_mem=8388608, BOOL literal=0, BOOL never_nl=0, BOOL dot_nl=0, BOOL case_sensitive=1, BOOL perl_classes=0, BOOL word_boundary=0, BOOL one_line=0)
+   new xset = set(
+      ENUM {none, start, both} anchor=none,
+      BOOL utf8=0,
+      BOOL posix_syntax=0,
+      BOOL longest_match=0,
+      INT max_mem=8388608,
+      BOOL literal=0,
+      BOOL never_nl=0,
+      BOOL dot_nl=0,
+      BOOL case_sensitive=1,
+      BOOL perl_classes=0,
+      BOOL word_boundary=0,
+      BOOL one_line=0
+   )

 Initialize a set object that represents several patterns combined by
 alternation -- ``|`` for "or".
@@ -802,12 +921,18 @@ Example::

 .. _func_set.add:

-set.add
-------
+set.add(...)
+------------

 ::

-	VOID set.add(STRING, STRING string=0, BACKEND backend=0, BOOL save=0, BOOL never_capture=0)
+      VOID xset.add(
+            STRING,
+            STRING string=0,
+            BACKEND backend=0,
+            BOOL save=0,
+            BOOL never_capture=0
+      )

 Add the given pattern to the set. If the pattern is invalid,
 ``.add()`` fails, and the VCL will fail to load, with an error message
@@ -871,14 +996,11 @@ Example::
  # See the documentation of the .string() and .backend() methods
  # below for uses of the parameters string and backend for .add().

-.. _func_set.compile:
-
-set.compile
-----------

-::
+.. _func_set.compile:

-	VOID set.compile()
+VOID xset.compile()
+-------------------

 Compile the compound pattern represented by the set -- an alternation
 of all patterns added by ``.add()``.
@@ -896,14 +1018,11 @@ will fail.

 See above for examples.

-.. _func_set.match:
-
-set.match
---------

-::
+.. _func_set.match:

-	BOOL set.match(STRING)
+BOOL xset.match(STRING)
+-----------------------

 Returns ``true`` if the given string matches the compound pattern
 represented by the set, i.e. if it matches any of the patterns that
@@ -923,14 +1042,11 @@ Example::
     call do_when_a_host_matched;
  }

-.. _func_set.matched:
-
-set.matched
-----------

-::
+.. _func_set.matched:

-	BOOL set.matched(INT)
+BOOL xset.matched(INT)
+----------------------

 Returns ``true`` after a successful match if the ``nth`` pattern that
 was added to the set is among the patterns that matched, ``false``
@@ -971,14 +1087,11 @@ Example::
      }
  }

-.. _func_set.nmatches:
-
-set.nmatches
------------

-::
+.. _func_set.nmatches:

-	INT set.nmatches()
+INT xset.nmatches()
+-------------------

 Returns the number of patterns that were matched by the most recent
 invocation of ``.match()`` for the same object in the same client or
@@ -1000,14 +1113,11 @@ Example::
              + " patterns from the set");
  }

-.. _func_set.which:
-
-set.which
---------

-::
+.. _func_set.which:

-	INT set.which(ENUM {FIRST,LAST,UNIQUE} select=UNIQUE)
+INT xset.which(ENUM {FIRST, LAST, UNIQUE} select=UNIQUE)
+--------------------------------------------------------

 Returns a number indicating which pattern in a set matched in the most
 recent invocation of ``.match()`` in the client or backend
@@ -1067,14 +1177,18 @@ Examples::
          # unsuccessful.
      }

+
 .. _func_set.string:

-set.string
----------
+STRING xset.string(INT n, ENUM select)
+--------------------------------------

 ::

-	STRING set.string(INT n=0, ENUM {FIRST,LAST,UNIQUE} select=UNIQUE)
+      STRING xset.string(
+            INT n=0,
+            ENUM {FIRST, LAST, UNIQUE} select=UNIQUE
+      )

 Returns the string associated with the `nth` pattern added to the set,
 or with the pattern in the set that matched in the most recent call to
@@ -1200,14 +1314,18 @@ Examples::

  # vcl_synth is implemented as shown above

+
 .. _func_set.backend:

-set.backend
-----------
+BACKEND xset.backend(INT n, ENUM select)
+----------------------------------------

 ::

-	BACKEND set.backend(INT n=0, ENUM {FIRST,LAST,UNIQUE} select=UNIQUE)
+      BACKEND xset.backend(
+            INT n=0,
+            ENUM {FIRST, LAST, UNIQUE} select=UNIQUE
+      )

 Returns the backend associated with the `nth` pattern added to the
 set, or with the pattern in the set that matched in the most recent
@@ -1253,14 +1371,21 @@ Example::
      }
  }

+
 .. _func_set.sub:

-set.sub
-------
+set.sub(...)
+------------

 ::

-	STRING set.sub(STRING text, STRING rewrite, STRING fallback="**SUB METHOD FAILED**", INT n=0, ENUM {FIRST,LAST,UNIQUE} select=UNIQUE)
+      STRING xset.sub(
+            STRING text,
+            STRING rewrite,
+            STRING fallback="**SUB METHOD FAILED**",
+            INT n=0,
+            ENUM {FIRST, LAST, UNIQUE} select=UNIQUE
+      )

 Returns the result of the method call ``.sub(text, rewrite, fallback)``,
 as documented above for the ``regex`` interface, invoked on the `nth`
@@ -1324,14 +1449,14 @@ Examples::
      }
  }

-.. _func_version:

-version
-------

-::

-	STRING version()
+
+.. _func_version:
+
+STRING version()
+----------------

 Return the version string for this VMOD.

@@ -1342,13 +1467,12 @@ Example::
 REQUIREMENTS
 ============

-The VMOD requires the Varnish master branch, and is not compatible
-with any current released versions of Varnish. See the source
+The VMOD requires Varnish since version 6.0.0. See the source
 repository for versions of the VMOD that are compatible with other
 Varnish versions.

 It requires the RE2 library, and has been tested against RE2 versions
-2015-06-01 through 2017-11-01.
+2015-06-01 through 2018-04-01.

 INSTALLATION
 ============
@@ -1396,12 +1520,13 @@ SEE ALSO
  * Series of articles motivating the design of RE2, with discussion
    of how RE2 compares with PCRE

+
 COPYRIGHT
 =========

 ::

-  Copyright (c) 2016-2017 UPLEX Nils Goroll Systemoptimierung
+  Copyright (c) 2016-2018 UPLEX Nils Goroll Systemoptimierung
  All rights reserved
 
  Author: Geoffrey Simmons <geoffrey.simmons@uplex.de>

--- a/configure.ac
+++ b/configure.ac
 AC_PREREQ([2.68])
-AC_INIT([libvmod-re2], [trunk], [varnish-support@uplex.de], [vmod-re2])
+AC_INIT([libvmod-re2], [1.4.4], [varnish-support@uplex.de], [vmod-re2])
 AC_COPYRIGHT([Copyright 2016-2017 UPLEX - Nils Goroll Systemoptimierung])
 AC_CONFIG_MACRO_DIR([m4])
 AC_CONFIG_AUX_DIR([build-aux])
@@ -39,7 +39,7 @@ if echo "$RE2_LIBS" | grep -- '-L' >/dev/null ; then
 	fi
 fi

-VARNISH_PREREQ([master])
+VARNISH_PREREQ([6.0.0])
 VARNISH_VMODS([re2])

 VMOD_TESTS="$(cd $srcdir/src && echo tests/*.vtc)"

--- a/src/vmod_re2.vcc
+++ b/src/vmod_re2.vcc
 #-
-# Copyright (c) 2016-2017 UPLEX Nils Goroll Systemoptimierung
+# Copyright (c) 2016-2018 UPLEX Nils Goroll Systemoptimierung
 # All rights reserved
 #
 # Author: Geoffrey Simmons <geoffrey.simmons@uplex.de>
@@ -9,8 +9,15 @@

 $Module re2 3 Varnish Module for access to the Google RE2 regular expression engine

+$Synopsis manual
+
+SYNOPSIS
+========
+
 ::

+  import re2;
+
  # regex object interface
  new OBJECT = re2.regex(STRING pattern [, <regex options>])
  BOOL <obj>.match(STRING)
@@ -1185,13 +1192,12 @@ Example::
 REQUIREMENTS
 ============

-The VMOD requires the Varnish master branch, and is not compatible
-with any current released versions of Varnish. See the source
+The VMOD requires Varnish since version 6.0.0. See the source
 repository for versions of the VMOD that are compatible with other
 Varnish versions.

 It requires the RE2 library, and has been tested against RE2 versions
-2015-06-01 through 2017-11-01.
+2015-06-01 through 2018-04-01.

 INSTALLATION
 ============