Update doc formatting for changes in the vmodtool since Varnish 5.0.

README.rst

@@ -198,38 +198,28 @@ turned off.
 CONTENTS
 ========
 
-* STRING backref(PRIV_TASK, INT, STRING)
-* STRING extract(STRING, STRING, STRING, STRING, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
+* 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)
-* Object regex
-* STRING regex.backref(INT, STRING)
-* STRING regex.extract(STRING, STRING, STRING)
-* BOOL regex.match(STRING)
-* STRING regex.namedref(STRING, STRING)
-* STRING regex.sub(STRING, STRING, STRING)
-* STRING regex.suball(STRING, STRING, STRING)
-* Object set
-* VOID set.add(STRING)
-* VOID set.compile()
-* BOOL set.match(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:
 
-Object regex
-============
+regex
+-----
 
+::
 
-Prototype
-  new OBJECT = re2.regex(STRING pattern [, <regex options>])
+	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)
 
-Description
-  Create a regex object from ``pattern`` and the given options (or option
-  defaults). If the pattern is invalid, then VCL will fail to load and the VCC
-  compiler will emit an error message.
+Create a regex object from ``pattern`` and the given options (or
+option defaults). If the pattern is invalid, then VCL will fail to
+load and the VCC compiler will emit an error message.
 
 Example::
 
@@ -244,15 +234,15 @@ Example::
 
 .. _func_regex.match:
 
-BOOL regex.match(STRING)
-------------------------
+regex.match
+-----------
+
+::
 
-Prototype
 	BOOL regex.match(STRING)
 
-Description
-  Returns ``true`` if and only if the compiled regex matches the given
-  string; corresponds to VCL's infix operator ``~``.
+Returns ``true`` if and only if the compiled regex matches the given
+string; corresponds to VCL's infix operator ``~``.
 
 Example::
 
@@ -262,48 +252,51 @@ Example::
 
 .. _func_regex.backref:
 
-STRING regex.backref(INT, STRING)
----------------------------------
-
-Prototype
-	STRING regex.backref(INT ref, STRING fallback)
-
-Description
-  Returns the `nth` captured subexpression from the most recent successful
-  call of the ``.match()`` method for this object in the same client or backend,
-  context, or a fallback string in case the capture fails. Backref 0 indicates
-  the entire matched string. Thus this function behaves like the ``\n`` in the
-  native VCL functions ``regsub`` and ``regsuball``, and the ``$1``, ``$2`` ...
-  variables in Perl.
-
-  Since Varnish client and backend operations run in different threads,
-  ``.backref()`` can only refer back to a ``.match()`` call in the same
-  thread. Thus a ``.backref()`` call in any of the ``vcl_backend_*``
-  subroutines -- the backend context -- refers back to a previous ``.match()``
-  in any of those same subroutines; and a call in any of the other VCL
-  subroutines -- the client context -- refers back to a ``.match()`` in the
-  same client context.
-
-  After unsuccessful matches, the ``fallback`` string is returned for any call
-  to ``.backref()``. The default value of ``fallback`` is ``"**BACKREF METHOD
-  FAILED**"``. ``.backref()`` always fails after a failed match, even if
-  ``.match()`` had been called successfully before the failure.
-
-  ``.backref()`` may also return ``fallback`` after a successful match, if
-  no captured group in the matching string corresponds to the backref number.
-  For example, when the pattern ``(a|(b))c`` matches the string ``ac``, there
-  is no backref 2, since nothing matches ``b`` in the string.
-
-  The VCL infix operators ``~`` and ``!~`` do not affect this method, nor do
-  the functions ``regsub`` or ``regsuball``. Nor is it affected by the matches
-  performed by any other method or function in this VMOD (such as the ``sub()``,
-  ``suball()`` or ``extract()`` methods or functions, or the ``set`` object's
-  ``.match()`` method).
-
-  ``.backref()`` fails, returning ``fallback`` and writing an error
-  message to the Varnish log with the ``VCL_Error`` tag, under the
-  following conditions (even if a previous match was successful and a
-  substring could have been captured):
+regex.backref
+-------------
+
+::
+
+	STRING regex.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
+client or backend, context, or a fallback string in case the capture
+fails. Backref 0 indicates the entire matched string. Thus this
+function behaves like the ``\n`` in the native VCL functions
+``regsub`` and ``regsuball``, and the ``$1``, ``$2`` ... variables in
+Perl.
+
+Since Varnish client and backend operations run in different threads,
+``.backref()`` can only refer back to a ``.match()`` call in the same
+thread. Thus a ``.backref()`` call in any of the ``vcl_backend_*``
+subroutines -- the backend context -- refers back to a previous
+``.match()`` in any of those same subroutines; and a call in any of
+the other VCL subroutines -- the client context -- refers back to a
+``.match()`` in the same client context.
+
+After unsuccessful matches, the ``fallback`` string is returned for
+any call to ``.backref()``. The default value of ``fallback`` is
+``"**BACKREF METHOD FAILED**"``. ``.backref()`` always fails after a
+failed match, even if ``.match()`` had been called successfully before
+the failure.
+
+``.backref()`` may also return ``fallback`` after a successful match,
+if no captured group in the matching string corresponds to the backref
+number. For example, when the pattern ``(a|(b))c`` matches the string
+``ac``, there is no backref 2, since nothing matches ``b`` in the
+string.
+
+The VCL infix operators ``~`` and ``!~`` do not affect this method,
+nor do the functions ``regsub`` or ``regsuball``. Nor is it affected
+by the matches performed by any other method or function in this VMOD
+(such as the ``sub()``, ``suball()`` or ``extract()`` methods or
+functions, or the ``set`` object's ``.match()`` method).
+
+``.backref()`` fails, returning ``fallback`` and writing an error
+message to the Varnish log with the ``VCL_Error`` tag, under the
+following conditions (even if a previous match was successful and a
+substring could have been captured):
 
 * The ``fallback`` string is undefined, for example if set from an unset
   header variable.
@@ -323,34 +316,38 @@ Example::
 
 .. _func_regex.namedref:
 
-STRING regex.namedref(STRING, STRING)
--------------------------------------
+regex.namedref
+--------------
+
+::
 
-Prototype
-	STRING regex.namedref(STRING name, STRING fallback)
+	STRING regex.namedref(STRING name, STRING fallback="**NAMEDREF METHOD FAILED**")
 
-Description
-  Returns the captured subexpression designated by ``name`` from the most
-  recent successful call to ``.match()`` in the current context (client or
-  backend), or ``fallback`` in case of failure.
+Returns the captured subexpression designated by ``name`` from the
+most recent successful call to ``.match()`` in the current context
+(client or backend), or ``fallback`` in case of failure.
 
-  Named capturing groups are written in RE2 as: ``(?P<name>re)``. (Note that
-  this syntax with ``P``, inspired by Python, differs from the notation for
-  named capturing groups in PCRE.) Thus when ``(?P<foo>.+)bar$`` matches
-  ``bazbar``, then ``.namedref("foo")`` returns ``baz``.
+Named capturing groups are written in RE2 as: ``(?P<name>re)``. (Note
+that this syntax with ``P``, inspired by Python, differs from the
+notation for named capturing groups in PCRE.) Thus when
+``(?P<foo>.+)bar$`` matches ``bazbar``, then ``.namedref("foo")``
+returns ``baz``.
 
-  Note that a named capturing group can also be referenced as a numbered group.
-  So in the previous example, ``.backref(1)`` also returns ``baz``.
+Note that a named capturing group can also be referenced as a numbered
+group. So in the previous example, ``.backref(1)`` also returns
+``baz``.
 
-  ``fallback`` is returned when ``.namedref()`` is called after an
-  unsuccessful match. The default fallback is ``"**NAMEDREF METHOD FAILED**"``.
+``fallback`` is returned when ``.namedref()`` is called after an
+unsuccessful match. The default fallback is ``"**NAMEDREF METHOD
+FAILED**"``.
 
-  Like ``.backref()``, ``.namedref()`` is not affected by native VCL regex
-  operations, nor by any other matches performed by methods or functions of
-  the VMOD, except for a prior ``.match()`` for the same object.
+Like ``.backref()``, ``.namedref()`` is not affected by native VCL
+regex operations, nor by any other matches performed by methods or
+functions of the VMOD, except for a prior ``.match()`` for the same
+object.
 
-  ``.namedref()`` fails, returning ``fallback`` and logging a ``VCL_Error``
-  message, if:
+``.namedref()`` fails, returning ``fallback`` and logging a
+``VCL_Error`` message, if:
 
 * The ``fallback`` string is undefined.
 * ``name`` is undefined or the empty string.
@@ -373,25 +370,25 @@ Example::
 
 .. _func_regex.sub:
 
-STRING regex.sub(STRING, STRING, STRING)
-----------------------------------------
+regex.sub
+---------
+
+::
 
-Prototype
-	STRING regex.sub(STRING text, STRING rewrite, STRING fallback)
+	STRING regex.sub(STRING text, STRING rewrite, STRING fallback="**SUB METHOD FAILED**")
 
-Description
-  If the compiled pattern for this regex object matches ``text``, then
-  return the result of replacing the first match in ``text`` with ``rewrite``.
-  Within ``rewrite``, ``\1`` through ``\9`` can be used to insert the
-  the numbered capturing group from the pattern, and ``\0`` to insert the
-  entire matching text. This method corresponds to the VCL native function
-  ``regsub()``.
+If the compiled pattern for this regex object matches ``text``, then
+return the result of replacing the first match in ``text`` with
+``rewrite``. Within ``rewrite``, ``\1`` through ``\9`` can be used to
+insert the the numbered capturing group from the pattern, and ``\0``
+to insert the entire matching text. This method corresponds to the VCL
+native function ``regsub()``.
 
-  ``fallback`` is returned if the pattern does not match ``text``. The default
-  fallback is ``"**SUB METHOD FAILED**"``.
+``fallback`` is returned if the pattern does not match ``text``. The
+default fallback is ``"**SUB METHOD FAILED**"``.
 
-  ``.sub()`` fails, returning ``fallback`` and logging a ``VCL_Error`` message,
-  if:
+``.sub()`` fails, returning ``fallback`` and logging a ``VCL_Error``
+message, if:
 
 * Any of ``text``, ``rewrite`` or ``fallback`` are undefined.
 * There is insufficient workspace for the rewritten string.
@@ -410,22 +407,23 @@ Example::
 
 .. _func_regex.suball:
 
-STRING regex.suball(STRING, STRING, STRING)
--------------------------------------------
+regex.suball
+------------
 
-Prototype
-	STRING regex.suball(STRING text, STRING rewrite, STRING fallback)
+::
+
+	STRING regex.suball(STRING text, STRING rewrite, STRING fallback="**SUBALL METHOD FAILED**")
 
-Description
-  Like ``.sub()``, except that all successive non-overlapping matches in
-  ``text`` are replaced with ``rewrite``. This method corresponds to VCL
-  native ``regsuball()``.
+Like ``.sub()``, except that all successive non-overlapping matches in
+``text`` are replaced with ``rewrite``. This method corresponds to VCL
+native ``regsuball()``.
 
-  The default fallback is ``"**SUBALL METHOD FAILED**"``. ``.suball()``
-  fails under the same conditions as ``.sub()``.
+The default fallback is ``"**SUBALL METHOD FAILED**"``. ``.suball()``
+fails under the same conditions as ``.sub()``.
 
-  Since only non-overlapping matches are substituted, replacing ``"ana"``
-  within ``"banana"`` only results in one substitution, not two.
+Since only non-overlapping matches are substituted, replacing
+``"ana"`` within ``"banana"`` only results in one substitution, not
+two.
 
 Example::
 
@@ -441,19 +439,19 @@ Example::
 
 .. _func_regex.extract:
 
-STRING regex.extract(STRING, STRING, STRING)
---------------------------------------------
+regex.extract
+-------------
+
+::
 
-Prototype
-	STRING regex.extract(STRING text, STRING rewrite, STRING fallback)
+	STRING regex.extract(STRING text, STRING rewrite, STRING fallback="**EXTRACT METHOD FAILED**")
 
-Description
-  If the compiled pattern for this regex object matches ``text``, then
-  return ``rewrite`` with substitutions from the matching portions of
-  ``text``. Non-matching substrings of ``text`` are ignored.
+If the compiled pattern for this regex object matches ``text``, then
+return ``rewrite`` with substitutions from the matching portions of
+``text``. Non-matching substrings of ``text`` are ignored.
 
-  The default fallback is ``"**EXTRACT METHOD FAILED**"``. Like ``.sub()``
-  and ``.suball()``, ``.extract()`` fails if:
+The default fallback is ``"**EXTRACT METHOD FAILED**"``. Like
+``.sub()`` and ``.suball()``, ``.extract()`` fails if:
 
 * Any of ``text``, ``rewrite`` or ``fallback`` are undefined.
 * There is insufficient workspace for the rewritten string.
@@ -474,19 +472,19 @@ regex functional interface
 
 .. _func_match:
 
-BOOL match(PRIV_TASK, STRING, STRING, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
-------------------------------------------------------------------------------------------------------------
+match
+-----
+
+::
 
-Prototype
-	BOOL match(PRIV_TASK, STRING pattern, STRING subject, BOOL utf8, BOOL posix_syntax, BOOL longest_match, INT max_mem, BOOL literal, BOOL never_nl, BOOL dot_nl, BOOL never_capture, BOOL case_sensitive, BOOL perl_classes, BOOL word_boundary, BOOL one_line)
+	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)
 
-Description
-  Like the ``regex.match()`` method, return ``true`` if  ``pattern`` matches
-  ``subject``, where ``pattern`` is compiled with the given options (or default
-  options) on each invocation.
+Like the ``regex.match()`` method, return ``true`` if ``pattern``
+matches ``subject``, where ``pattern`` is compiled with the given
+options (or default options) on each invocation.
 
-  If ``pattern`` fails to compile, then an error message is logged with
-  the ``VCL_Error`` tag, and ``false`` is returned.
+If ``pattern`` fails to compile, then an error message is logged with
+the ``VCL_Error`` tag, and ``false`` is returned.
 
 Example::
 
@@ -497,26 +495,26 @@ Example::
 
 .. _func_backref:
 
-STRING backref(PRIV_TASK, INT, STRING)
---------------------------------------
+backref
+-------
 
-Prototype
-	STRING backref(PRIV_TASK, INT ref, STRING fallback)
+::
+
+	STRING backref(PRIV_TASK, INT ref, STRING fallback="**BACKREF FUNCTION FAILED**")
 
-Description
-  Returns the `nth` captured subexpression from the most recent successful
-  call of the ``match()`` function in the current client or backend context,
-  or a fallback string if the capture fails. The default ``fallback`` is
-  ``"**BACKREF FUNCTION FAILED**"``.
+Returns the `nth` captured subexpression from the most recent
+successful call of the ``match()`` function in the current client or
+backend context, or a fallback string if the capture fails. The
+default ``fallback`` is ``"**BACKREF FUNCTION FAILED**"``.
 
-  Similarly to the ``regex.backref()`` method, ``fallback`` is returned
-  after any failed invocation of the ``match()`` function, or if there
-  is no captured group corresponding to the backref number. The function
-  is not affected by native VCL regex operations, or any other method or
-  function of the VMOD except for the ``match()`` function.
+Similarly to the ``regex.backref()`` method, ``fallback`` is returned
+after any failed invocation of the ``match()`` function, or if there
+is no captured group corresponding to the backref number. The function
+is not affected by native VCL regex operations, or any other method or
+function of the VMOD except for the ``match()`` function.
 
-  The function fails, returning ``fallback`` and logging a ``VCL_Error``
-  message, under the same conditions as the corresponding method:
+The function fails, returning ``fallback`` and logging a ``VCL_Error``
+message, under the same conditions as the corresponding method:
 
 * ``fallback`` is undefined.
 * ``never_capture`` was true in the previous invocation of the ``match()``
@@ -536,23 +534,23 @@ Example::
 
 .. _func_namedref:
 
-STRING namedref(PRIV_TASK, STRING, STRING)
-------------------------------------------
+namedref
+--------
 
-Prototype
-	STRING namedref(PRIV_TASK, STRING name, STRING fallback)
+::
 
-Description
-  Returns the captured subexpression designated by ``name`` from the most
-  recent successful call to the ``match()`` function in the current context, or
-  ``fallback`` in case of failure. The default fallback is ``"**NAMEDREF
-  FUNCTION FAILED**"``.
+	STRING namedref(PRIV_TASK, STRING name, STRING fallback="**NAMEDREF FUNCTION FAILED**")
 
-  The function returns ``fallback`` when the previous invocation of the
-  ``match()`` function failed, and is only affected by use of the ``match()``
-  function. The function fails, returning ``fallback`` and logging a
-  ``VCL_Error`` message, under the same conditions as the corresponding
-  method:
+Returns the captured subexpression designated by ``name`` from the
+most recent successful call to the ``match()`` function in the current
+context, or ``fallback`` in case of failure. The default fallback is
+``"**NAMEDREF FUNCTION FAILED**"``.
+
+The function returns ``fallback`` when the previous invocation of the
+``match()`` function failed, and is only affected by use of the
+``match()`` function. The function fails, returning ``fallback`` and
+logging a ``VCL_Error`` message, under the same conditions as the
+corresponding method:
 
 * ``fallback`` is undefined.
 * ``name`` is undefined or the empty string.
@@ -570,24 +568,24 @@ Example::
 
 .. _func_sub:
 
-STRING sub(STRING, STRING, STRING, STRING, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
------------------------------------------------------------------------------------------------------------------
+sub
+---
+
+::
 
-Prototype
-	STRING sub(STRING pattern, STRING text, STRING rewrite, STRING fallback, BOOL utf8, BOOL posix_syntax, BOOL longest_match, INT max_mem, BOOL literal, BOOL never_nl, BOOL dot_nl, BOOL never_capture, BOOL case_sensitive, BOOL perl_classes, BOOL word_boundary, BOOL one_line)
+	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)
 
-Description
-  Compiles ``pattern`` with the given options, and if it matches ``text``,
-  then return the result of replacing the first match in ``text`` with
-  ``rewrite``. As with the ``regex.sub()`` method, ``\0`` through ``\9``
-  may be used in ``rewrite`` to substitute captured groups from the
-  pattern.
+Compiles ``pattern`` with the given options, and if it matches
+``text``, then return the result of replacing the first match in
+``text`` with ``rewrite``. As with the ``regex.sub()`` method, ``\0``
+through ``\9`` may be used in ``rewrite`` to substitute captured
+groups from the pattern.
 
-  ``fallback`` is returned if the pattern does not match ``text``. The default
-  fallback is ``"**SUB FUNCTION FAILED**"``.
+``fallback`` is returned if the pattern does not match ``text``. The
+default fallback is ``"**SUB FUNCTION FAILED**"``.
 
-  ``sub()`` fails, returning ``fallback`` and logging a ``VCL_Error`` message,
-  if:
+``sub()`` fails, returning ``fallback`` and logging a ``VCL_Error``
+message, if:
 
 * ``pattern`` cannot be compiled.
 * Any of ``text``, ``rewrite`` or ``fallback`` are undefined.
@@ -603,18 +601,18 @@ Example::
 
 .. _func_suball:
 
-STRING suball(STRING, STRING, STRING, STRING, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
---------------------------------------------------------------------------------------------------------------------
+suball
+------
 
-Prototype
-	STRING suball(STRING pattern, STRING text, STRING rewrite, STRING fallback, BOOL utf8, BOOL posix_syntax, BOOL longest_match, INT max_mem, BOOL literal, BOOL never_nl, BOOL dot_nl, BOOL never_capture, BOOL case_sensitive, BOOL perl_classes, BOOL word_boundary, BOOL one_line)
+::
 
-Description
-  Like the ``sub()`` function, except that all successive non-overlapping
-  matches in ``text`` are replace with ``rewrite``.
+	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)
 
-  The default fallback is ``"**SUBALL FUNCTION FAILED**"``. The ``suball()``
-  function fails under the same conditions as ``sub()``.
+Like the ``sub()`` function, except that all successive
+non-overlapping matches in ``text`` are replace with ``rewrite``.
+
+The default fallback is ``"**SUBALL FUNCTION FAILED**"``. The
+``suball()`` function fails under the same conditions as ``sub()``.
 
 Example::
 
@@ -626,19 +624,20 @@ Example::
 
 .. _func_extract:
 
-STRING extract(STRING, STRING, STRING, STRING, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
----------------------------------------------------------------------------------------------------------------------
+extract
+-------
+
+::
 
-Prototype
-	STRING extract(STRING pattern, STRING text, STRING rewrite, STRING fallback, BOOL utf8, BOOL posix_syntax, BOOL longest_match, INT max_mem, BOOL literal, BOOL never_nl, BOOL dot_nl, BOOL never_capture, BOOL case_sensitive, BOOL perl_classes, BOOL word_boundary, BOOL one_line)
+	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)
 
-Description
-  Compiles ``pattern`` with the given options, and if it matches ``text``,
-  then return ``rewrite`` with substitutions from the matching portions of
-  ``text``, ignoring the non-matching portions.
+Compiles ``pattern`` with the given options, and if it matches
+``text``, then return ``rewrite`` with substitutions from the matching
+portions of ``text``, ignoring the non-matching portions.
 
-  The default fallback is ``"**EXTRACT FUNCTION FAILED**"``. The ``extract()``
-  function fails under the same conditions as ``sub()`` and ``suball()``.
+The default fallback is ``"**EXTRACT FUNCTION FAILED**"``. The
+``extract()`` function fails under the same conditions as ``sub()``
+and ``suball()``.
 
 Example::
 
@@ -649,34 +648,35 @@ Example::
 
 .. _obj_set:
 
-Object set
-==========
+set
+---
 
+::
 
-Prototype
-  new OBJECT = re2.set([ENUM anchor] [, <regex options>])
+	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)
 
-Description
-  Initialize a set object that represents several patterns combined by
-  alternation -- ``|`` for "or".
+Initialize a set object that represents several patterns combined by
+alternation -- ``|`` for "or".
   
-  Optional parameters control the interpretation of the resulting composed
-  pattern. The ``anchor`` parameter is an enum that can have the values
-  ``none``, ``start`` or ``both``, where ``none`` is the default. ``start``
-  means that each pattern is matched as if it begins with ``^`` for
-  start-of-text, and ``both`` means that each pattern is anchored with both
-  ``^`` at the beginning and ``$`` for end-of-text at the end. ``none`` means
-  that each pattern is interpreted as a partial match (although individual
-  patterns within the set may have either of ``^`` of ``$``).
+Optional parameters control the interpretation of the resulting
+composed pattern. The ``anchor`` parameter is an enum that can have
+the values ``none``, ``start`` or ``both``, where ``none`` is the
+default. ``start`` means that each pattern is matched as if it begins
+with ``^`` for start-of-text, and ``both`` means that each pattern is
+anchored with both ``^`` at the beginning and ``$`` for end-of-text at
+the end. ``none`` means that each pattern is interpreted as a partial
+match (although individual patterns within the set may have either of
+``^`` of ``$``).
 
-  For example, if a set is initialized with ``anchor=both``, and the patterns
-  ``foo`` and ``bar`` are added, then matches against the set match a string
-  against ``^foo$|^bar$``, or equivalently ``^(foo|bar)$``.
+For example, if a set is initialized with ``anchor=both``, and the
+patterns ``foo`` and ``bar`` are added, then matches against the set
+match a string against ``^foo$|^bar$``, or equivalently
+``^(foo|bar)$``.
   
-  The usual regex options can be set, which then control matching against
-  the resulting composed pattern. However, the ``never_capture`` option
-  cannot be set, and is always implicitly true, since backrefs and
-  namedrefs are not possible with sets.
+The usual regex options can be set, which then control matching
+against the resulting composed pattern. However, the ``never_capture``
+option cannot be set, and is always implicitly true, since backrefs
+and namedrefs are not possible with sets.
 
 Example::
 
@@ -697,25 +697,25 @@ Example::
 
 .. _func_set.add:
 
-VOID set.add(STRING)
---------------------
+set.add
+-------
+
+::
 
-Prototype
 	VOID set.add(STRING)
 
-Description
-  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 describing
-  the problem.
+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
+describing the problem.
 
-  ``.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 effect.
-  If it is called in ``vcl_init`` after ``.compile()``, then the VCL load
-  will fail with an error message.
+``.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
+effect. If it is called in ``vcl_init`` after ``.compile()``, then the
+VCL load will fail with an error message.
 
-  In other words, add all patterns to the set in ``vcl_init``, and finally
-  call ``.compile()`` when you're done.
+In other words, add all patterns to the set in ``vcl_init``, and
+finally call ``.compile()`` when you're done.
 
 Example::
 
@@ -732,43 +732,44 @@ Example::
 
 .. _func_set.compile:
 
-VOID set.compile()
-------------------
+set.compile
+-----------
+
+::
 
-Prototype
 	VOID set.compile()
 
-Description
-  Compile the compound pattern represented by the set -- an alternation of
-  all patterns added by ``.add()``.
+Compile the compound pattern represented by the set -- an alternation
+of all patterns added by ``.add()``.
 
-  ``.compile()`` may fail if the ``max_mem`` setting is not large enough
-  for the composed pattern. In that case, the VCL load will fail with an
-  error message (then consider a larger value for ``max_mem`` in the set
-  constructor).
+``.compile()`` may fail if the ``max_mem`` setting is not large enough
+for the composed pattern. In that case, the VCL load will fail with an
+error message (then consider a larger value for ``max_mem`` in the set
+constructor).
 
-  ``.compile()`` MUST be called in ``vcl_init``, and MAY NOT be called
-  more than once for a set object. If it is called in any other subroutine,
-  a ``VCL_Error`` message is logged, and the call has no effect. If it
-  is called a second time in ``vcl_init``, the VCL load will fail.
+``.compile()`` MUST be called in ``vcl_init``, and MAY NOT be called
+more than once for a set object. If it is called in any other
+subroutine, a ``VCL_Error`` message is logged, and the call has no
+effect. If it is called a second time in ``vcl_init``, the VCL load
+will fail.
 
-  See above for examples.
+See above for examples.
 
 .. _func_set.match:
 
-BOOL set.match(STRING)
-----------------------
+set.match
+---------
+
+::
 
-Prototype
 	BOOL set.match(STRING)
 
-Description
-  Returns ``true`` if the given string matches the compound pattern
-  represented by the set, i.e. if it matches any of the patterns that
-  were added to the set.
+Returns ``true`` if the given string matches the compound pattern
+represented by the set, i.e. if it matches any of the patterns that
+were added to the set.
 
-  ``.match()`` MUST be called after ``.compile()``; otherwise the
-  match always fails.
+``.match()`` MUST be called after ``.compile()``; otherwise the match
+always fails.
 
 Example::
 
@@ -778,14 +779,14 @@ Example::
 
 .. _func_version:
 
-STRING version()
-----------------
+version
+-------
+
+::
 
-Prototype
 	STRING version()
 
-Description
-  Return the version string for this VMOD.
+Return the version string for this VMOD.
 
 Example::
 
@@ -912,3 +913,16 @@ project. See LICENSE for details.
 
 * Copyright (c) 2016 UPLEX Nils Goroll Systemoptimierung
 
+COPYRIGHT
+=========
+
+::
+
+  Copyright (c) 2016 UPLEX Nils Goroll Systemoptimierung
+  All rights reserved
+ 
+  Author: Geoffrey Simmons <geoffrey.simmons@uplex.de>
+ 
+  See LICENSE
+ 
+

src/vmod_re2.vcc

@@ -186,13 +186,9 @@ $Object regex(STRING pattern, BOOL utf8=0, BOOL posix_syntax=0,
 	      BOOL case_sensitive=1, BOOL perl_classes=0,
 	      BOOL word_boundary=0, BOOL one_line=0)
 
-Prototype
-  new OBJECT = re2.regex(STRING pattern [, <regex options>])
-
-Description
-  Create a regex object from ``pattern`` and the given options (or option
-  defaults). If the pattern is invalid, then VCL will fail to load and the VCC
-  compiler will emit an error message.
+Create a regex object from ``pattern`` and the given options (or
+option defaults). If the pattern is invalid, then VCL will fail to
+load and the VCC compiler will emit an error message.
 
 Example::
 
@@ -207,9 +203,8 @@ Example::
 
 $Method BOOL .match(STRING)
 
-Description
-  Returns ``true`` if and only if the compiled regex matches the given
-  string; corresponds to VCL's infix operator ``~``.
+Returns ``true`` if and only if the compiled regex matches the given
+string; corresponds to VCL's infix operator ``~``.
 
 Example::
 
@@ -219,42 +214,44 @@ Example::
 
 $Method STRING .backref(INT ref, STRING fallback = "**BACKREF METHOD FAILED**")
 
-Description
-  Returns the `nth` captured subexpression from the most recent successful
-  call of the ``.match()`` method for this object in the same client or backend,
-  context, or a fallback string in case the capture fails. Backref 0 indicates
-  the entire matched string. Thus this function behaves like the ``\n`` in the
-  native VCL functions ``regsub`` and ``regsuball``, and the ``$1``, ``$2`` ...
-  variables in Perl.
-
-  Since Varnish client and backend operations run in different threads,
-  ``.backref()`` can only refer back to a ``.match()`` call in the same
-  thread. Thus a ``.backref()`` call in any of the ``vcl_backend_*``
-  subroutines -- the backend context -- refers back to a previous ``.match()``
-  in any of those same subroutines; and a call in any of the other VCL
-  subroutines -- the client context -- refers back to a ``.match()`` in the
-  same client context.
-
-  After unsuccessful matches, the ``fallback`` string is returned for any call
-  to ``.backref()``. The default value of ``fallback`` is ``"**BACKREF METHOD
-  FAILED**"``. ``.backref()`` always fails after a failed match, even if
-  ``.match()`` had been called successfully before the failure.
-
-  ``.backref()`` may also return ``fallback`` after a successful match, if
-  no captured group in the matching string corresponds to the backref number.
-  For example, when the pattern ``(a|(b))c`` matches the string ``ac``, there
-  is no backref 2, since nothing matches ``b`` in the string.
-
-  The VCL infix operators ``~`` and ``!~`` do not affect this method, nor do
-  the functions ``regsub`` or ``regsuball``. Nor is it affected by the matches
-  performed by any other method or function in this VMOD (such as the ``sub()``,
-  ``suball()`` or ``extract()`` methods or functions, or the ``set`` object's
-  ``.match()`` method).
-
-  ``.backref()`` fails, returning ``fallback`` and writing an error
-  message to the Varnish log with the ``VCL_Error`` tag, under the
-  following conditions (even if a previous match was successful and a
-  substring could have been captured):
+Returns the `nth` captured subexpression from the most recent
+successful call of the ``.match()`` method for this object in the same
+client or backend, context, or a fallback string in case the capture
+fails. Backref 0 indicates the entire matched string. Thus this
+function behaves like the ``\n`` in the native VCL functions
+``regsub`` and ``regsuball``, and the ``$1``, ``$2`` ... variables in
+Perl.
+
+Since Varnish client and backend operations run in different threads,
+``.backref()`` can only refer back to a ``.match()`` call in the same
+thread. Thus a ``.backref()`` call in any of the ``vcl_backend_*``
+subroutines -- the backend context -- refers back to a previous
+``.match()`` in any of those same subroutines; and a call in any of
+the other VCL subroutines -- the client context -- refers back to a
+``.match()`` in the same client context.
+
+After unsuccessful matches, the ``fallback`` string is returned for
+any call to ``.backref()``. The default value of ``fallback`` is
+``"**BACKREF METHOD FAILED**"``. ``.backref()`` always fails after a
+failed match, even if ``.match()`` had been called successfully before
+the failure.
+
+``.backref()`` may also return ``fallback`` after a successful match,
+if no captured group in the matching string corresponds to the backref
+number. For example, when the pattern ``(a|(b))c`` matches the string
+``ac``, there is no backref 2, since nothing matches ``b`` in the
+string.
+
+The VCL infix operators ``~`` and ``!~`` do not affect this method,
+nor do the functions ``regsub`` or ``regsuball``. Nor is it affected
+by the matches performed by any other method or function in this VMOD
+(such as the ``sub()``, ``suball()`` or ``extract()`` methods or
+functions, or the ``set`` object's ``.match()`` method).
+
+``.backref()`` fails, returning ``fallback`` and writing an error
+message to the Varnish log with the ``VCL_Error`` tag, under the
+following conditions (even if a previous match was successful and a
+substring could have been captured):
 
 * The ``fallback`` string is undefined, for example if set from an unset
   header variable.
@@ -275,28 +272,31 @@ Example::
 $Method STRING .namedref(STRING name,
                          STRING fallback = "**NAMEDREF METHOD FAILED**")
 
-Description
-  Returns the captured subexpression designated by ``name`` from the most
-  recent successful call to ``.match()`` in the current context (client or
-  backend), or ``fallback`` in case of failure.
+Returns the captured subexpression designated by ``name`` from the
+most recent successful call to ``.match()`` in the current context
+(client or backend), or ``fallback`` in case of failure.
 
-  Named capturing groups are written in RE2 as: ``(?P<name>re)``. (Note that
-  this syntax with ``P``, inspired by Python, differs from the notation for
-  named capturing groups in PCRE.) Thus when ``(?P<foo>.+)bar$`` matches
-  ``bazbar``, then ``.namedref("foo")`` returns ``baz``.
+Named capturing groups are written in RE2 as: ``(?P<name>re)``. (Note
+that this syntax with ``P``, inspired by Python, differs from the
+notation for named capturing groups in PCRE.) Thus when
+``(?P<foo>.+)bar$`` matches ``bazbar``, then ``.namedref("foo")``
+returns ``baz``.
 
-  Note that a named capturing group can also be referenced as a numbered group.
-  So in the previous example, ``.backref(1)`` also returns ``baz``.
+Note that a named capturing group can also be referenced as a numbered
+group. So in the previous example, ``.backref(1)`` also returns
+``baz``.
 
-  ``fallback`` is returned when ``.namedref()`` is called after an
-  unsuccessful match. The default fallback is ``"**NAMEDREF METHOD FAILED**"``.
+``fallback`` is returned when ``.namedref()`` is called after an
+unsuccessful match. The default fallback is ``"**NAMEDREF METHOD
+FAILED**"``.
 
-  Like ``.backref()``, ``.namedref()`` is not affected by native VCL regex
-  operations, nor by any other matches performed by methods or functions of
-  the VMOD, except for a prior ``.match()`` for the same object.
+Like ``.backref()``, ``.namedref()`` is not affected by native VCL
+regex operations, nor by any other matches performed by methods or
+functions of the VMOD, except for a prior ``.match()`` for the same
+object.
 
-  ``.namedref()`` fails, returning ``fallback`` and logging a ``VCL_Error``
-  message, if:
+``.namedref()`` fails, returning ``fallback`` and logging a
+``VCL_Error`` message, if:
 
 * The ``fallback`` string is undefined.
 * ``name`` is undefined or the empty string.
@@ -320,19 +320,18 @@ Example::
 $Method STRING .sub(STRING text, STRING rewrite,
                     STRING fallback = "**SUB METHOD FAILED**")
 
-Description
-  If the compiled pattern for this regex object matches ``text``, then
-  return the result of replacing the first match in ``text`` with ``rewrite``.
-  Within ``rewrite``, ``\1`` through ``\9`` can be used to insert the
-  the numbered capturing group from the pattern, and ``\0`` to insert the
-  entire matching text. This method corresponds to the VCL native function
-  ``regsub()``.
+If the compiled pattern for this regex object matches ``text``, then
+return the result of replacing the first match in ``text`` with
+``rewrite``. Within ``rewrite``, ``\1`` through ``\9`` can be used to
+insert the the numbered capturing group from the pattern, and ``\0``
+to insert the entire matching text. This method corresponds to the VCL
+native function ``regsub()``.
 
-  ``fallback`` is returned if the pattern does not match ``text``. The default
-  fallback is ``"**SUB METHOD FAILED**"``.
+``fallback`` is returned if the pattern does not match ``text``. The
+default fallback is ``"**SUB METHOD FAILED**"``.
 
-  ``.sub()`` fails, returning ``fallback`` and logging a ``VCL_Error`` message,
-  if:
+``.sub()`` fails, returning ``fallback`` and logging a ``VCL_Error``
+message, if:
 
 * Any of ``text``, ``rewrite`` or ``fallback`` are undefined.
 * There is insufficient workspace for the rewritten string.
@@ -352,16 +351,16 @@ Example::
 $Method STRING .suball(STRING text, STRING rewrite,
                        STRING fallback = "**SUBALL METHOD FAILED**")
 
-Description
-  Like ``.sub()``, except that all successive non-overlapping matches in
-  ``text`` are replaced with ``rewrite``. This method corresponds to VCL
-  native ``regsuball()``.
+Like ``.sub()``, except that all successive non-overlapping matches in
+``text`` are replaced with ``rewrite``. This method corresponds to VCL
+native ``regsuball()``.
 
-  The default fallback is ``"**SUBALL METHOD FAILED**"``. ``.suball()``
-  fails under the same conditions as ``.sub()``.
+The default fallback is ``"**SUBALL METHOD FAILED**"``. ``.suball()``
+fails under the same conditions as ``.sub()``.
 
-  Since only non-overlapping matches are substituted, replacing ``"ana"``
-  within ``"banana"`` only results in one substitution, not two.
+Since only non-overlapping matches are substituted, replacing
+``"ana"`` within ``"banana"`` only results in one substitution, not
+two.
 
 Example::
 
@@ -378,13 +377,12 @@ Example::
 $Method STRING .extract(STRING text, STRING rewrite,
                         STRING fallback = "**EXTRACT METHOD FAILED**")
 
-Description
-  If the compiled pattern for this regex object matches ``text``, then
-  return ``rewrite`` with substitutions from the matching portions of
-  ``text``. Non-matching substrings of ``text`` are ignored.
+If the compiled pattern for this regex object matches ``text``, then
+return ``rewrite`` with substitutions from the matching portions of
+``text``. Non-matching substrings of ``text`` are ignored.
 
-  The default fallback is ``"**EXTRACT METHOD FAILED**"``. Like ``.sub()``
-  and ``.suball()``, ``.extract()`` fails if:
+The default fallback is ``"**EXTRACT METHOD FAILED**"``. Like
+``.sub()`` and ``.suball()``, ``.extract()`` fails if:
 
 * Any of ``text``, ``rewrite`` or ``fallback`` are undefined.
 * There is insufficient workspace for the rewritten string.
@@ -410,13 +408,12 @@ $Function BOOL match(PRIV_TASK, STRING pattern, STRING subject, BOOL utf8=0,
 		     BOOL case_sensitive=1, BOOL perl_classes=0,
 		     BOOL word_boundary=0, BOOL one_line=0)
 
-Description
-  Like the ``regex.match()`` method, return ``true`` if  ``pattern`` matches
-  ``subject``, where ``pattern`` is compiled with the given options (or default
-  options) on each invocation.
+Like the ``regex.match()`` method, return ``true`` if ``pattern``
+matches ``subject``, where ``pattern`` is compiled with the given
+options (or default options) on each invocation.
 
-  If ``pattern`` fails to compile, then an error message is logged with
-  the ``VCL_Error`` tag, and ``false`` is returned. 
+If ``pattern`` fails to compile, then an error message is logged with
+the ``VCL_Error`` tag, and ``false`` is returned.
 
 Example::
 
@@ -428,20 +425,19 @@ Example::
 $Function STRING backref(PRIV_TASK, INT ref,
                          STRING fallback = "**BACKREF FUNCTION FAILED**")
 
-Description
-  Returns the `nth` captured subexpression from the most recent successful
-  call of the ``match()`` function in the current client or backend context,
-  or a fallback string if the capture fails. The default ``fallback`` is
-  ``"**BACKREF FUNCTION FAILED**"``.
+Returns the `nth` captured subexpression from the most recent
+successful call of the ``match()`` function in the current client or
+backend context, or a fallback string if the capture fails. The
+default ``fallback`` is ``"**BACKREF FUNCTION FAILED**"``.
 
-  Similarly to the ``regex.backref()`` method, ``fallback`` is returned
-  after any failed invocation of the ``match()`` function, or if there
-  is no captured group corresponding to the backref number. The function
-  is not affected by native VCL regex operations, or any other method or
-  function of the VMOD except for the ``match()`` function.
+Similarly to the ``regex.backref()`` method, ``fallback`` is returned
+after any failed invocation of the ``match()`` function, or if there
+is no captured group corresponding to the backref number. The function
+is not affected by native VCL regex operations, or any other method or
+function of the VMOD except for the ``match()`` function.
 
-  The function fails, returning ``fallback`` and logging a ``VCL_Error``
-  message, under the same conditions as the corresponding method:
+The function fails, returning ``fallback`` and logging a ``VCL_Error``
+message, under the same conditions as the corresponding method:
 
 * ``fallback`` is undefined.
 * ``never_capture`` was true in the previous invocation of the ``match()``
@@ -462,17 +458,16 @@ Example::
 $Function STRING namedref(PRIV_TASK, STRING name,
                           STRING fallback = "**NAMEDREF FUNCTION FAILED**")
 
-Description
-  Returns the captured subexpression designated by ``name`` from the most
-  recent successful call to the ``match()`` function in the current context, or
-  ``fallback`` in case of failure. The default fallback is ``"**NAMEDREF
-  FUNCTION FAILED**"``.
+Returns the captured subexpression designated by ``name`` from the
+most recent successful call to the ``match()`` function in the current
+context, or ``fallback`` in case of failure. The default fallback is
+``"**NAMEDREF FUNCTION FAILED**"``.
 
-  The function returns ``fallback`` when the previous invocation of the
-  ``match()`` function failed, and is only affected by use of the ``match()``
-  function. The function fails, returning ``fallback`` and logging a
-  ``VCL_Error`` message, under the same conditions as the corresponding
-  method:
+The function returns ``fallback`` when the previous invocation of the
+``match()`` function failed, and is only affected by use of the
+``match()`` function. The function fails, returning ``fallback`` and
+logging a ``VCL_Error`` message, under the same conditions as the
+corresponding method:
 
 * ``fallback`` is undefined.
 * ``name`` is undefined or the empty string.
@@ -495,18 +490,17 @@ $Function STRING sub(STRING pattern, STRING text, STRING rewrite,
 		     BOOL dot_nl=0, BOOL never_capture=0, BOOL case_sensitive=1,
 		     BOOL perl_classes=0, BOOL word_boundary=0, BOOL one_line=0)
 
-Description
-  Compiles ``pattern`` with the given options, and if it matches ``text``,
-  then return the result of replacing the first match in ``text`` with
-  ``rewrite``. As with the ``regex.sub()`` method, ``\0`` through ``\9``
-  may be used in ``rewrite`` to substitute captured groups from the
-  pattern.
+Compiles ``pattern`` with the given options, and if it matches
+``text``, then return the result of replacing the first match in
+``text`` with ``rewrite``. As with the ``regex.sub()`` method, ``\0``
+through ``\9`` may be used in ``rewrite`` to substitute captured
+groups from the pattern.
 
-  ``fallback`` is returned if the pattern does not match ``text``. The default
-  fallback is ``"**SUB FUNCTION FAILED**"``.
+``fallback`` is returned if the pattern does not match ``text``. The
+default fallback is ``"**SUB FUNCTION FAILED**"``.
 
-  ``sub()`` fails, returning ``fallback`` and logging a ``VCL_Error`` message,
-  if:
+``sub()`` fails, returning ``fallback`` and logging a ``VCL_Error``
+message, if:
 
 * ``pattern`` cannot be compiled.
 * Any of ``text``, ``rewrite`` or ``fallback`` are undefined.
@@ -528,12 +522,11 @@ $Function STRING suball(STRING pattern, STRING text, STRING rewrite,
 			BOOL case_sensitive=1, BOOL perl_classes=0,
 			BOOL word_boundary=0, BOOL one_line=0)
 
-Description
-  Like the ``sub()`` function, except that all successive non-overlapping
-  matches in ``text`` are replace with ``rewrite``.
+Like the ``sub()`` function, except that all successive
+non-overlapping matches in ``text`` are replace with ``rewrite``.
 
-  The default fallback is ``"**SUBALL FUNCTION FAILED**"``. The ``suball()``
-  function fails under the same conditions as ``sub()``.
+The default fallback is ``"**SUBALL FUNCTION FAILED**"``. The
+``suball()`` function fails under the same conditions as ``sub()``.
 
 Example::
 
@@ -551,13 +544,13 @@ $Function STRING extract(STRING pattern, STRING text, STRING rewrite,
 			 BOOL case_sensitive=1, BOOL perl_classes=0,
 			 BOOL word_boundary=0, BOOL one_line=0)
 
-Description
-  Compiles ``pattern`` with the given options, and if it matches ``text``,
-  then return ``rewrite`` with substitutions from the matching portions of
-  ``text``, ignoring the non-matching portions.
+Compiles ``pattern`` with the given options, and if it matches
+``text``, then return ``rewrite`` with substitutions from the matching
+portions of ``text``, ignoring the non-matching portions.
 
-  The default fallback is ``"**EXTRACT FUNCTION FAILED**"``. The ``extract()``
-  function fails under the same conditions as ``sub()`` and ``suball()``.
+The default fallback is ``"**EXTRACT FUNCTION FAILED**"``. The
+``extract()`` function fails under the same conditions as ``sub()``
+and ``suball()``.
 
 Example::
 
@@ -572,30 +565,28 @@ $Object set(ENUM { none, start, both } anchor="none", BOOL utf8=0,
 	    BOOL case_sensitive=1, BOOL perl_classes=0, BOOL word_boundary=0,
 	    BOOL one_line=0)
 
-Prototype
-  new OBJECT = re2.set([ENUM anchor] [, <regex options>])
-
-Description
-  Initialize a set object that represents several patterns combined by
-  alternation -- ``|`` for "or".
-  
-  Optional parameters control the interpretation of the resulting composed
-  pattern. The ``anchor`` parameter is an enum that can have the values
-  ``none``, ``start`` or ``both``, where ``none`` is the default. ``start``
-  means that each pattern is matched as if it begins with ``^`` for
-  start-of-text, and ``both`` means that each pattern is anchored with both
-  ``^`` at the beginning and ``$`` for end-of-text at the end. ``none`` means
-  that each pattern is interpreted as a partial match (although individual
-  patterns within the set may have either of ``^`` of ``$``).
-
-  For example, if a set is initialized with ``anchor=both``, and the patterns
-  ``foo`` and ``bar`` are added, then matches against the set match a string
-  against ``^foo$|^bar$``, or equivalently ``^(foo|bar)$``.
-  
-  The usual regex options can be set, which then control matching against
-  the resulting composed pattern. However, the ``never_capture`` option
-  cannot be set, and is always implicitly true, since backrefs and
-  namedrefs are not possible with sets.
+Initialize a set object that represents several patterns combined by
+alternation -- ``|`` for "or".
+  
+Optional parameters control the interpretation of the resulting
+composed pattern. The ``anchor`` parameter is an enum that can have
+the values ``none``, ``start`` or ``both``, where ``none`` is the
+default. ``start`` means that each pattern is matched as if it begins
+with ``^`` for start-of-text, and ``both`` means that each pattern is
+anchored with both ``^`` at the beginning and ``$`` for end-of-text at
+the end. ``none`` means that each pattern is interpreted as a partial
+match (although individual patterns within the set may have either of
+``^`` of ``$``).
+
+For example, if a set is initialized with ``anchor=both``, and the
+patterns ``foo`` and ``bar`` are added, then matches against the set
+match a string against ``^foo$|^bar$``, or equivalently
+``^(foo|bar)$``.
+  
+The usual regex options can be set, which then control matching
+against the resulting composed pattern. However, the ``never_capture``
+option cannot be set, and is always implicitly true, since backrefs
+and namedrefs are not possible with sets.
 
 Example::
 
@@ -616,19 +607,18 @@ Example::
 
 $Method VOID .add(STRING)
 
-Description
-  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 describing
-  the problem.
+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
+describing the problem.
 
-  ``.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 effect.
-  If it is called in ``vcl_init`` after ``.compile()``, then the VCL load
-  will fail with an error message.
+``.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
+effect. If it is called in ``vcl_init`` after ``.compile()``, then the
+VCL load will fail with an error message.
 
-  In other words, add all patterns to the set in ``vcl_init``, and finally
-  call ``.compile()`` when you're done.
+In other words, add all patterns to the set in ``vcl_init``, and
+finally call ``.compile()`` when you're done.
 
 Example::
 
@@ -645,31 +635,30 @@ Example::
 
 $Method VOID .compile()
 
-Description
-  Compile the compound pattern represented by the set -- an alternation of
-  all patterns added by ``.add()``.
+Compile the compound pattern represented by the set -- an alternation
+of all patterns added by ``.add()``.
 
-  ``.compile()`` may fail if the ``max_mem`` setting is not large enough
-  for the composed pattern. In that case, the VCL load will fail with an
-  error message (then consider a larger value for ``max_mem`` in the set
-  constructor).
+``.compile()`` may fail if the ``max_mem`` setting is not large enough
+for the composed pattern. In that case, the VCL load will fail with an
+error message (then consider a larger value for ``max_mem`` in the set
+constructor).
 
-  ``.compile()`` MUST be called in ``vcl_init``, and MAY NOT be called
-  more than once for a set object. If it is called in any other subroutine,
-  a ``VCL_Error`` message is logged, and the call has no effect. If it
-  is called a second time in ``vcl_init``, the VCL load will fail.
+``.compile()`` MUST be called in ``vcl_init``, and MAY NOT be called
+more than once for a set object. If it is called in any other
+subroutine, a ``VCL_Error`` message is logged, and the call has no
+effect. If it is called a second time in ``vcl_init``, the VCL load
+will fail.
 
-  See above for examples.
+See above for examples.
 
 $Method BOOL .match(STRING)
 
-Description
-  Returns ``true`` if the given string matches the compound pattern
-  represented by the set, i.e. if it matches any of the patterns that
-  were added to the set.
+Returns ``true`` if the given string matches the compound pattern
+represented by the set, i.e. if it matches any of the patterns that
+were added to the set.
 
-  ``.match()`` MUST be called after ``.compile()``; otherwise the
-  match always fails.
+``.match()`` MUST be called after ``.compile()``; otherwise the match
+always fails.
 
 Example::
 
@@ -679,8 +668,7 @@ Example::
 
 $Function STRING version()
 
-Description
-  Return the version string for this VMOD.
+Return the version string for this VMOD.
 
 Example::