Update README

README.rst

@@ -31,6 +31,12 @@ SYNOPSIS
   BOOL <obj>.match_body(req_body | bereq_body | resp_body
                         [, INT limit] [, INT limit_recursion])
 
+  # filter interface (includes all of the above)
+  new <obj> = re.regex(STRING [, INT limit] [, INT limit_recursion]
+                       , forbody=true)
+  <obj>.substitute_match(INT, STRING)
+  set [be]resp.filters = "<obj>"
+
   # function interface
   BOOL re.match_dyn(STRING [, INT limit] [, INT limit_recursion])
   STRING re.backref_dyn(INT [, STRING fallback])
@@ -44,6 +50,10 @@ DESCRIPTION
 
 .. _regsuball(): https://varnish-cache.org/docs/trunk/reference/vcl.html#regsuball-str-regex-sub
 
+.. _beresp.filters: https://varnish-cache.org/docs/trunk/reference/vcl-var.html#beresp-filters
+
+.. _resp.filters: https://varnish-cache.org/docs/trunk/reference/vcl-var.html#resp-filters
+
 Varnish Module (VMOD) for matching strings against regular expressions,
 and for extracting captured substrings after matches.
 
@@ -96,6 +106,10 @@ the ``vcl_backend_*`` subroutines and returns ``true``, then
 subsequent calls to ``backref`` in the same backend scope extract
 substrings from the matched substring.
 
+By setting the ``asfilter`` parameter to true, a regex object can also
+be configured to add a filter for performing substitutions on
+bodies. See `xregex.substitute_match()`_ for details and examples.
+
 The VMOD also supports dynamic regex matching with the ``match_dyn``
 and ``backref_dyn`` functions::
 
@@ -125,8 +139,8 @@ never changes during the lifetime of VCL, use ``match``.
 
 .. _re.regex():
 
-new xregex = re.regex(STRING, INT limit, INT limit_recursion, BOOL forbody)
----------------------------------------------------------------------------
+new xregex = re.regex(STRING, INT limit, INT limit_recursion, BOOL forbody, BOOL asfilter)
+------------------------------------------------------------------------------------------
 
 ::
 
@@ -134,7 +148,8 @@ new xregex = re.regex(STRING, INT limit, INT limit_recursion, BOOL forbody)
       STRING,
       INT limit=1000,
       INT limit_recursion=1000,
-      BOOL forbody=0
+      BOOL forbody=0,
+      BOOL asfilter=0
    )
 
 Description
@@ -154,6 +169,14 @@ Description
 	`xregex.match_body()`_ method is to be called on the
 	object.
 
+	If the optional ``asfilter`` parameter is true, the vmod
+	registers itself as a Varnish Fetch Processor (VFP) for use in
+	`beresp.filters`_ and as a Varnish Delivery Processor (VDP)
+	for use in `resp.filters`_. In this setup, the
+	`xregex.substitute_match()`_ and `xregex.substitute_all()`_
+	methods can be used to define replacements for matches on the
+	body.
+
 Example
 	``new myregex = re.regex("\bmax-age\s*=\s*(\d+)");``
 
@@ -227,6 +250,8 @@ Description
 	should first be cached by calling
 	``std.cache_req_body(<size>)``.
 
+	Lookarounds are not supported.
+
 Example::
 
 	sub vcl_init {
@@ -288,9 +313,94 @@ Description
 	is emitted to the Varnish log using the ``VCL_Error`` tag, and
 	the fallback string is returned.
 
+	Lookarounds are not supported.
+
 Example
         ``set beresp.ttl = std.duration(myregex.backref(1, "120"), 120s);``
 
+.. _xregex.substitute_match():
+
+VOID xregex.substitute_match(INT, STRING)
+-----------------------------------------
+
+Description
+	This method defines substitutions for regular expression
+	replacement ("regsub") operations on HTTP bodies.
+
+	It can only be used on `re.regex()`_ objects initiated with
+	the ``asfilter`` argument set to ``true``, or a VCL failure
+	will be triggered.
+
+	The INT argument defines to which match the substitution is to
+	be applied: For ``1``, it applies to the first match, for
+	``2`` to the second etc. A value of ``0`` defines the default
+	substitution which is applied if a specific substitution is
+	not defined. Negative values trigger a VCL failure.
+
+	If no substitution is defined for a match (and there is no
+	default), the matched sub-string is left unchanged.
+
+	The STRING argument defines the substitution to apply, exactly
+	like the ``sub`` (third) argument of the `regsub()`_ built-in
+	VCL function: ``\0`` (which can also be spelled ``\&``) is
+	replaced with the entire matched string, and ``\n`` is
+	replaced with the contents of subgroup *n* in the matched
+	string.
+
+	To have any effect, the regex object must be used as a fetch
+	or delivery filter.
+
+Example
+	For occurrences of the string "reiher" in the response body,
+	replace the first with "czapla", the second with "eier" and
+	all others with "heron". The response is returned uncompressed
+	even if the client supported compression because there
+	currently is no ``gzip`` VDP in Varnish-Cache::
+
+	    sub vcl_init {
+		new reiher = re.regex("r(ei)h(er)", asfilter = true);
+	    }
+	    sub vcl_deliver {
+		unset req.http.Accept-Encoding;
+		set resp.filters += " reiher";
+		reiher.substitute_match(1, "czapla");
+		reiher.substitute_match(2, "\1\2");
+		reiher.substitute_match(0, "heron");
+	    }
+
+.. _xregex.substitute_all():
+
+VOID xregex.substitute_all(STRING)
+----------------------------------
+
+Description
+	This method instructs the named filter object to replace all
+	matches with the STRING argument.
+
+	It is a shorthand for calling::
+
+	  xregex.clear_substitutions();
+	  xregex.substitute_match(0, STRING);
+
+	See `xregex.substitute_match()`_ for when to use this method.
+
+.. _xregex.clear_substitutions():
+
+VOID xregex.clear_substitutions()
+---------------------------------
+
+Description
+	This method clears all previous substitution definions through
+	`xregex.substitute_match()`_ and `xregex.substitute_all()`_.
+
+	It is not required because VCL code could always be written
+	sucht hat only one code patch ever calls
+	`xregex.substitute_match()`_ and `xregex.substitute_all()`_,
+	but it is provided to allow for simpler VCL for handling
+	exceptional cases.
+
+	See `xregex.substitute_match()`_ for when to use this method.
+
 .. _re.match_dyn():
 
 BOOL match_dyn(STRING, STRING, INT limit, INT limit_recursion)