Document the set.sub() method.

README.rst

@@ -39,9 +39,12 @@ import re2 [from "path"] ;
   BOOL re2.match(STRING pattern, STRING subject [, <regex options>])
   STRING re2.backref(INT ref)
   STRING re2.namedref(STRING name)
-  STRING re2.sub(STRING pattern, STRING text, STRING rewrite [, <regex options>])
-  STRING re2.suball(STRING pattern, STRING text, STRING rewrite [, <regex options>])
-  STRING re2.extract(STRING pattern, STRING text, STRING rewrite [, <regex options>])
+  STRING re2.sub(STRING pattern, STRING text, STRING rewrite
+                 [, <regex options>])
+  STRING re2.suball(STRING pattern, STRING text, STRING rewrite
+                    [, <regex options>])
+  STRING re2.extract(STRING pattern, STRING text, STRING rewrite
+                     [, <regex options>])
 
   # set object interface
   new OBJECT = re2.set([ENUM anchor] [, <regex options>])
@@ -53,6 +56,7 @@ import re2 [from "path"] ;
   INT <obj>.which([ENUM select])
   STRING <obj>.string([INT n,] [ENUM select])
   BACKEND <obj>.backend([INT n,] [ENUM select])
+  STRING <obj>.sub(STRING text, STRING rewrite [, INT n] [, ENUM select])
 
   # VMOD version
   STRING re2.version()
@@ -300,9 +304,9 @@ CONTENTS
 ========
 
 * regex(STRING, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
-* BOOL match(PRIV_TASK, STRING, STRING, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
-* STRING backref(PRIV_TASK, INT, STRING)
-* STRING namedref(PRIV_TASK, STRING, STRING)
+* 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)
@@ -578,7 +582,7 @@ match
 
 ::
 
-	BOOL match(PRIV_TASK, 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
@@ -601,7 +605,7 @@ backref
 
 ::
 
-	STRING backref(PRIV_TASK, 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
@@ -640,7 +644,7 @@ namedref
 
 ::
 
-	STRING namedref(PRIV_TASK, 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
@@ -817,6 +821,25 @@ pattern after it matches successfully. ``string`` and ``backend``
 default to NULL; that is; by default the pattern is not associated
 with any such value.
 
+If ``save`` is true, then the given pattern is compiled and saved as a
+``regex`` object, just as if the ``regex`` constructor described above
+is invoked. This object is stored internally in the ``set`` object as
+an independent matcher, separate from "compound" pattern formed by the
+set as an alternation of the patterns added to it. By default,
+``save`` is **false**.
+
+When the ``.match()`` method on the set is successful, and one of the
+patterns that matched is associated with a saved internal ``regex``
+object, then that object may be used for subsequent method invocations
+such as ``.sub()`` on the set object, whose meanings are the same as
+documented above for ``regex`` objects. Details are described below.
+
+When an internal ``regex`` object is saved (i.e. when ``save`` is
+true), it is compiled with the same options that were provided to the
+set object in the constructor. The ``never_capture`` option can also
+be set to false for the individual regex, even though it is implicitly
+set to true for the full set object (default is false).
+
 ``.add()`` MUST be called in ``vcl_init``, and MAY NOT be called after
 ``.compile()``.  If ``.add()`` is called in any other subroutine, an
 error message with ``VCL_Error`` is logged, and the call has no
@@ -828,8 +851,9 @@ finally call ``.compile()`` when you're done.
 
 When the ``.matched(INT)`` method is called after a successful match,
 the numbering corresponds to the order in which patterns were added.
-The same is true of the INT arguments that may be given for the
-``.string()`` or ``.backend()`` methods.
+The same is true of the INT arguments that may be given for methods
+such as ``.string()``, ``.backend()`` or ``.sub()``, as described
+below.
 
 Example::
 
@@ -1042,15 +1066,6 @@ Examples::
           # unsuccessful.
       }
 
-.. _func_set.sub:
-
-set.sub
--------
-
-::
-
-	STRING set.sub(STRING text, STRING rewrite, STRING fallback="**SUB METHOD FAILED**", INT n=0, ENUM {FIRST,LAST} select=0)
-
 .. _func_set.string:
 
 set.string
@@ -1062,48 +1077,59 @@ set.string
 
 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
-``.match()`` in the same task scope (client or backend context).
-
-If ``n`` > 0, then return the string associated with the `nth` pattern
-added to the set with the ``string`` parameter of the ``.add()``
-method, counting from 1. This will return the `nth` string in any
-context, regardless of whether ``.match()`` was called previously, or
-whether a previous call returned ``true`` or ``false``.
-
-If ``n`` <= 0, then return the string associated with a pattern in the
-set that matched successfully in the most recent call to ``.match()``
-in the task scope. Since ``n`` is 0 by default, ``n`` can be left out
-for this purpose.
-
-If ``n`` <= 0 and exactly one pattern in the set matched in the most
-recent invocation of ``.match()`` (and hence ``.nmatches()`` returns
-1), then the string associated with that pattern is returned. The
-``select`` parameter is ignored in this case. Thus ``.string()``
-can be used for this purpose with no arguments.
-
-If ``n`` <= 0 and more than one pattern matched in the most recent
-``.match()`` call (``.nmatches()`` > 1), then the string returned is
-determined by the ``select`` parameter. As with ``.which()``,
-``FIRST`` and ``LAST`` specify that the first or last matching pattern
-added via the ``.add()`` method is chosen, and the string associated
-with that pattern is returned.
+``.match()`` in the same task scope (client or backend context). The
+string set with the ``string`` parameter of the ``.add()`` method
+during ``vcl_init`` is returned.
+
+The pattern is identified with the parameters ``n`` and ``select``
+according to these rules, which also hold for all further ``set``
+methods documented in the following.
+
+* If ``n`` > 0, then select the `nth` pattern added to the set with
+  the ``.add()`` method, counting from 1. This identifies the `nth`
+  pattern in any context, regardless of whether ``.match()`` was
+  called previously, or whether a previous call returned ``true`` or
+  ``false``. The ``select`` parameter is ignored in this case.
+
+* If ``n`` <= 0, then select a pattern in the set that matched
+  successfully in the most recent call to ``.match()`` in the same
+  task scope. Since ``n`` is 0 by default, ``n`` can be left out for
+  this purpose.
+
+* If ``n`` <= 0 and exactly one pattern in the set matched in the most
+  recent invocation of ``.match()`` (and hence ``.nmatches()`` returns
+  1), then select that pattern. The ``select`` parameter is ignored in
+  this case. So when exactly one pattern in the set matched, both
+  ``n`` and ``select`` can be left out.
+
+* If ``n`` <= 0 and more than one pattern matched in the most recent
+  ``.match()`` call (``.nmatches()`` > 1), then the selection of a
+  pattern is determined by the ``select`` parameter. As with
+  ``.which()``, ``FIRST`` and ``LAST`` specify the first or last
+  matching pattern added via the ``.add()`` method.
+
+For the pattern selected by these rules, return the string that was
+set with the ``string`` parameter in the ``.add()`` method that added
+the pattern to the set.
 
 ``.string()`` fails, returning NULL with an a ``VCL_Error`` message in
 the log, if:
 
-* ``n`` is greater than the number of patterns in the set.
+* The values of ``n`` and ``select`` are invalid:
+
+  * ``n`` is greater than the number of patterns in the set.
 
-* ``n`` <= 0 (or left to the default), but ``.match()`` was not called
-  earlier in the same task scope (client or backend context).
+  * ``n`` <= 0 (or left to the default), but ``.match()`` was not
+    called earlier in the same task scope (client or backend context).
 
-* ``n`` <= 0, but the previous ``.match()`` call returned ``false``.
+  * ``n`` <= 0, but the previous ``.match()`` call returned ``false``.
 
-* ``n`` <= 0 and no value is given for the ``select`` ENUM, but more
-  than one pattern matched in the previous ``.match()`` call.
+  * ``n`` <= 0 and no value is given for the ``select`` ENUM, but more
+    than one pattern matched in the previous ``.match()`` call.
 
-* A pattern from the set is selected as described above, but no string
-  was associated with that pattern; that is, the ``string`` parameter
-  was not set in the ``.add()`` call that added the pattern.
+* No string was associated with the pattern selected by ``n`` and
+  ``select``; that is, the ``string`` parameter was not set in the
+  ``.add()`` call that added the pattern.
 
 Examples::
 
@@ -1187,25 +1213,13 @@ call to ``.match()`` in the same task scope (client or backend
 context).
 
 The rules for selecting a pattern from the set and its associated
-backend are the same as for ``.string()`` above:
-
-* If ``n`` > 0, then return the string associated with the `nth`
-  pattern added to the set with the ``backend`` parameter of the
-  ``.add()`` method, counting from 1 (independent of any previous
-  ``.match()`` call).
-
-* If ``n`` <= 0 (or left to the default) and exactly one pattern in
-  the set matched in the most recent invocation of ``.match()``
-  (``.nmatches()`` == 1), then return the backend associated with that
-  pattern (ignoring the value of ``select``).
-
-* If ``n`` <= 0 and ``.nmatches()`` > 1, then return the backend
-  associated with the first or last matching pattern in the set
-  as determined by the ``select`` parameter.
+backend based on ``n`` and ``select`` are the same as described above
+for ``.string()``.
 
 ``.backend()`` fails, returning NULL with an a ``VCL_Error`` message
 in the log, under the same conditions described for ``.string()``
-above.
+above -- ``n`` and ``select`` are invalid, or no backend was
+associated with the selected pattern with the ``.add()`` method.
 
 Example::
 
@@ -1237,6 +1251,77 @@ Example::
       }
   }
 
+.. _func_set.sub:
+
+set.sub
+-------
+
+::
+
+	STRING set.sub(STRING text, STRING rewrite, STRING fallback="**SUB METHOD FAILED**", INT n=0, ENUM {FIRST,LAST} select=0)
+
+Returns the result of the method call ``.sub(text, rewrite, fallback)``,
+as documented above for the ``regex`` interface, invoked on the `nth`
+pattern added to the set, or on the pattern in the set that matched in
+the most recent call to ``.match()`` in the same task scope.
+
+``.sub()`` requires that the pattern it identifies was saved as an
+internal ``regex`` object, by setting ``save`` to true when it was
+added with the ``.add()`` method.
+
+The associated pattern is determined by ``n`` and ``select`` according
+to the rules given above. If an internal ``regex`` object was saved
+for that pattern, then the result of the ``.sub()`` method invoked on
+that object is returned.
+
+``.sub()`` fails, returning NULL with a ``VCL_Error`` message in the
+log, if:
+
+* The values of ``n`` and ``select`` are invalid, according to the
+  rules given above.
+
+* ``save`` was false in the ``.add()`` method for the pattern
+  identified by ``n`` and ``select``; that is, no internal ``regex``
+  object was saved on which the ``.sub()`` method could have been
+  invoked.
+
+* The ``.sub()`` method invoked on the ``regex`` object fails for any
+  of the reasons described for ``regex.sub()``.
+
+Examples::
+
+  # Generate synthethic redirect responses on URLs that match a set of
+  # patterns, rewriting the URL according to the matched pattern.
+
+  # In this example, we set the new URL in the redirect location to
+  # the path that comes after the prefix of the original req.url.
+  sub vcl_init {
+      new matcher = re2.set(anchor=start);
+      matcher.add("/foo/(.*)", save=true);
+      matcher.add("/bar/(.*)", save=true);
+      matcher.add("/baz/(.*)", save=true);
+      matcher.compile();
+  }
+
+  sub vcl_recv {
+      if (matcher.match(req.url)) {
+          if (matcher.nmatches() != 1) {
+              return(fail);
+          }
+          return(synth(1301));
+      }
+  }
+
+  sub vcl_synth {
+      if (resp.status == 1301) {
+      	  # matcher.sub() rewrites the URL to the subpath after the
+	  # original prefix.
+          set resp.http.Location
+              = "http://www.otherdomain.org" + matcher.sub(req.url, "/\1");
+          return(deliver);
+      }
+  }
+
 .. _func_version:
 
 version

src/vmod_re2.vcc

@@ -24,9 +24,12 @@ $Module re2 3 Varnish Module for access to the Google RE2 regular expression eng
   BOOL re2.match(STRING pattern, STRING subject [, <regex options>])
   STRING re2.backref(INT ref)
   STRING re2.namedref(STRING name)
-  STRING re2.sub(STRING pattern, STRING text, STRING rewrite [, <regex options>])
-  STRING re2.suball(STRING pattern, STRING text, STRING rewrite [, <regex options>])
-  STRING re2.extract(STRING pattern, STRING text, STRING rewrite [, <regex options>])
+  STRING re2.sub(STRING pattern, STRING text, STRING rewrite
+                 [, <regex options>])
+  STRING re2.suball(STRING pattern, STRING text, STRING rewrite
+                    [, <regex options>])
+  STRING re2.extract(STRING pattern, STRING text, STRING rewrite
+                     [, <regex options>])
 
   # set object interface
   new OBJECT = re2.set([ENUM anchor] [, <regex options>])
@@ -38,6 +41,7 @@ $Module re2 3 Varnish Module for access to the Google RE2 regular expression eng
   INT <obj>.which([ENUM select])
   STRING <obj>.string([INT n,] [ENUM select])
   BACKEND <obj>.backend([INT n,] [ENUM select])
+  STRING <obj>.sub(STRING text, STRING rewrite [, INT n] [, ENUM select])
 
   # VMOD version
   STRING re2.version()
@@ -721,6 +725,25 @@ pattern after it matches successfully. ``string`` and ``backend``
 default to NULL; that is; by default the pattern is not associated
 with any such value.
 
+If ``save`` is true, then the given pattern is compiled and saved as a
+``regex`` object, just as if the ``regex`` constructor described above
+is invoked. This object is stored internally in the ``set`` object as
+an independent matcher, separate from "compound" pattern formed by the
+set as an alternation of the patterns added to it. By default,
+``save`` is **false**.
+
+When the ``.match()`` method on the set is successful, and one of the
+patterns that matched is associated with a saved internal ``regex``
+object, then that object may be used for subsequent method invocations
+such as ``.sub()`` on the set object, whose meanings are the same as
+documented above for ``regex`` objects. Details are described below.
+
+When an internal ``regex`` object is saved (i.e. when ``save`` is
+true), it is compiled with the same options that were provided to the
+set object in the constructor. The ``never_capture`` option can also
+be set to false for the individual regex, even though it is implicitly
+set to true for the full set object (default is false).
+
 ``.add()`` MUST be called in ``vcl_init``, and MAY NOT be called after
 ``.compile()``.  If ``.add()`` is called in any other subroutine, an
 error message with ``VCL_Error`` is logged, and the call has no
@@ -732,8 +755,9 @@ finally call ``.compile()`` when you're done.
 
 When the ``.matched(INT)`` method is called after a successful match,
 the numbering corresponds to the order in which patterns were added.
-The same is true of the INT arguments that may be given for the
-``.string()`` or ``.backend()`` methods.
+The same is true of the INT arguments that may be given for methods
+such as ``.string()``, ``.backend()`` or ``.sub()``, as described
+below.
 
 Example::
 
@@ -911,56 +935,63 @@ Examples::
           # unsuccessful.
       }
 
-$Method STRING .sub(STRING text, STRING rewrite,
-                    STRING fallback="**SUB METHOD FAILED**",
-		    INT n=0, ENUM {FIRST, LAST} select=0)
-
 $Method STRING .string(INT n=0, ENUM {FIRST, LAST} select=0)
 
 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
-``.match()`` in the same task scope (client or backend context).
-
-If ``n`` > 0, then return the string associated with the `nth` pattern
-added to the set with the ``string`` parameter of the ``.add()``
-method, counting from 1. This will return the `nth` string in any
-context, regardless of whether ``.match()`` was called previously, or
-whether a previous call returned ``true`` or ``false``.
-
-If ``n`` <= 0, then return the string associated with a pattern in the
-set that matched successfully in the most recent call to ``.match()``
-in the task scope. Since ``n`` is 0 by default, ``n`` can be left out
-for this purpose.
-
-If ``n`` <= 0 and exactly one pattern in the set matched in the most
-recent invocation of ``.match()`` (and hence ``.nmatches()`` returns
-1), then the string associated with that pattern is returned. The
-``select`` parameter is ignored in this case. Thus ``.string()``
-can be used for this purpose with no arguments.
-
-If ``n`` <= 0 and more than one pattern matched in the most recent
-``.match()`` call (``.nmatches()`` > 1), then the string returned is
-determined by the ``select`` parameter. As with ``.which()``,
-``FIRST`` and ``LAST`` specify that the first or last matching pattern
-added via the ``.add()`` method is chosen, and the string associated
-with that pattern is returned.
+``.match()`` in the same task scope (client or backend context). The
+string set with the ``string`` parameter of the ``.add()`` method
+during ``vcl_init`` is returned.
+
+The pattern is identified with the parameters ``n`` and ``select``
+according to these rules, which also hold for all further ``set``
+methods documented in the following.
+
+* If ``n`` > 0, then select the `nth` pattern added to the set with
+  the ``.add()`` method, counting from 1. This identifies the `nth`
+  pattern in any context, regardless of whether ``.match()`` was
+  called previously, or whether a previous call returned ``true`` or
+  ``false``. The ``select`` parameter is ignored in this case.
+
+* If ``n`` <= 0, then select a pattern in the set that matched
+  successfully in the most recent call to ``.match()`` in the same
+  task scope. Since ``n`` is 0 by default, ``n`` can be left out for
+  this purpose.
+
+* If ``n`` <= 0 and exactly one pattern in the set matched in the most
+  recent invocation of ``.match()`` (and hence ``.nmatches()`` returns
+  1), then select that pattern. The ``select`` parameter is ignored in
+  this case. So when exactly one pattern in the set matched, both
+  ``n`` and ``select`` can be left out.
+
+* If ``n`` <= 0 and more than one pattern matched in the most recent
+  ``.match()`` call (``.nmatches()`` > 1), then the selection of a
+  pattern is determined by the ``select`` parameter. As with
+  ``.which()``, ``FIRST`` and ``LAST`` specify the first or last
+  matching pattern added via the ``.add()`` method.
+
+For the pattern selected by these rules, return the string that was
+set with the ``string`` parameter in the ``.add()`` method that added
+the pattern to the set.
 
 ``.string()`` fails, returning NULL with an a ``VCL_Error`` message in
 the log, if:
 
-* ``n`` is greater than the number of patterns in the set.
+* The values of ``n`` and ``select`` are invalid:
+
+  * ``n`` is greater than the number of patterns in the set.
 
-* ``n`` <= 0 (or left to the default), but ``.match()`` was not called
-  earlier in the same task scope (client or backend context).
+  * ``n`` <= 0 (or left to the default), but ``.match()`` was not
+    called earlier in the same task scope (client or backend context).
 
-* ``n`` <= 0, but the previous ``.match()`` call returned ``false``.
+  * ``n`` <= 0, but the previous ``.match()`` call returned ``false``.
 
-* ``n`` <= 0 and no value is given for the ``select`` ENUM, but more
-  than one pattern matched in the previous ``.match()`` call.
+  * ``n`` <= 0 and no value is given for the ``select`` ENUM, but more
+    than one pattern matched in the previous ``.match()`` call.
 
-* A pattern from the set is selected as described above, but no string
-  was associated with that pattern; that is, the ``string`` parameter
-  was not set in the ``.add()`` call that added the pattern.
+* No string was associated with the pattern selected by ``n`` and
+  ``select``; that is, the ``string`` parameter was not set in the
+  ``.add()`` call that added the pattern.
 
 Examples::
 
@@ -1037,25 +1068,13 @@ call to ``.match()`` in the same task scope (client or backend
 context).
 
 The rules for selecting a pattern from the set and its associated
-backend are the same as for ``.string()`` above:
-
-* If ``n`` > 0, then return the string associated with the `nth`
-  pattern added to the set with the ``backend`` parameter of the
-  ``.add()`` method, counting from 1 (independent of any previous
-  ``.match()`` call).
-
-* If ``n`` <= 0 (or left to the default) and exactly one pattern in
-  the set matched in the most recent invocation of ``.match()``
-  (``.nmatches()`` == 1), then return the backend associated with that
-  pattern (ignoring the value of ``select``).
-
-* If ``n`` <= 0 and ``.nmatches()`` > 1, then return the backend
-  associated with the first or last matching pattern in the set
-  as determined by the ``select`` parameter.
+backend based on ``n`` and ``select`` are the same as described above
+for ``.string()``.
 
 ``.backend()`` fails, returning NULL with an a ``VCL_Error`` message
 in the log, under the same conditions described for ``.string()``
-above.
+above -- ``n`` and ``select`` are invalid, or no backend was
+associated with the selected pattern with the ``.add()`` method.
 
 Example::
 
@@ -1087,6 +1106,72 @@ Example::
       }
   }
 
+$Method STRING .sub(STRING text, STRING rewrite,
+                    STRING fallback="**SUB METHOD FAILED**",
+		    INT n=0, ENUM {FIRST, LAST} select=0)
+
+Returns the result of the method call ``.sub(text, rewrite, fallback)``,
+as documented above for the ``regex`` interface, invoked on the `nth`
+pattern added to the set, or on the pattern in the set that matched in
+the most recent call to ``.match()`` in the same task scope.
+
+``.sub()`` requires that the pattern it identifies was saved as an
+internal ``regex`` object, by setting ``save`` to true when it was
+added with the ``.add()`` method.
+
+The associated pattern is determined by ``n`` and ``select`` according
+to the rules given above. If an internal ``regex`` object was saved
+for that pattern, then the result of the ``.sub()`` method invoked on
+that object is returned.
+
+``.sub()`` fails, returning NULL with a ``VCL_Error`` message in the
+log, if:
+
+* The values of ``n`` and ``select`` are invalid, according to the
+  rules given above.
+
+* ``save`` was false in the ``.add()`` method for the pattern
+  identified by ``n`` and ``select``; that is, no internal ``regex``
+  object was saved on which the ``.sub()`` method could have been
+  invoked.
+
+* The ``.sub()`` method invoked on the ``regex`` object fails for any
+  of the reasons described for ``regex.sub()``.
+
+Examples::
+
+  # Generate synthethic redirect responses on URLs that match a set of
+  # patterns, rewriting the URL according to the matched pattern.
+
+  # In this example, we set the new URL in the redirect location to
+  # the path that comes after the prefix of the original req.url.
+  sub vcl_init {
+      new matcher = re2.set(anchor=start);
+      matcher.add("/foo/(.*)", save=true);
+      matcher.add("/bar/(.*)", save=true);
+      matcher.add("/baz/(.*)", save=true);
+      matcher.compile();
+  }
+
+  sub vcl_recv {
+      if (matcher.match(req.url)) {
+          if (matcher.nmatches() != 1) {
+              return(fail);
+          }
+          return(synth(1301));
+      }
+  }
+
+  sub vcl_synth {
+      if (resp.status == 1301) {
+      	  # matcher.sub() rewrites the URL to the subpath after the
+	  # original prefix.
+          set resp.http.Location
+              = "http://www.otherdomain.org" + matcher.sub(req.url, "/\1");
+          return(deliver);
+      }
+  }
+
 $Function STRING version()
 
 Return the version string for this VMOD.