More doc updates.

README.rst

@@ -519,8 +519,11 @@ Returns ``true`` if the STRING to be matched has a prefix that is in
 the set. The match is case insensitive if ``case_sensitive`` was set
 to ``false`` in the constructor.
 
-``.hasprefix()`` fails and returns ``false`` under the same conditions
-given for ``.match()`` above.
+``.hasprefix()`` invokes VCL failure under the same conditions given
+for ``.match()`` above. Like ``.match()``, ``.hasprefix()`` returns
+``false`` if the string to be matched is NULL, for example if it is an
+unset header, and a ``Notice`` message is emitted to the log (see
+`LOGGING`_).
 
 Example::
 
@@ -544,9 +547,8 @@ backend context).
 call, it returns the number of strings in the set that are prefixes of
 the string that was matched.
 
-``.nmatches()`` returns 0 and writes an error message to the log if
-there was no prior invocation of ``.match()`` or ``.hasprefix()`` in
-the same task scope.
+``.nmatches()`` invokes VCL failure if there was no prior invocation
+of ``.match()`` or ``.hasprefix()`` in the same task scope.
 
 Example::
 
@@ -575,27 +577,63 @@ BOOL xset.matched(INT n, ENUM select)
 
 After a successful ``.match()`` or ``.hasprefix()`` call for the same
 set object in the same task scope, return ``true`` if the element
-indicated by the INT parameter was matched. The numbering corresponds
-to the order of ``.add()`` invocations in ``vcl_init`` (starting from
-1).
+indicated by the ``n`` and ``select`` parameters was matched, according to
+the rules described above.
+
+For example if ``n`` > 0, ``.matched(n)`` returns ``true`` if and only
+if the ``n``-th element matched. The numbering corresponds to the
+order of ``.add()`` invocations in ``vcl_init`` (starting from 1). The
+``select`` parameter is ignored in this case.
+
+If ``n`` <= 0, the set element is determined by the ``select`` enum.
+In that case, ``.matched()`` returns ``true`` if and only if the
+element indicated by the enum was matched by the previous successful
+match operation. These distinctions are only relevant if the previous
+operation was ``.hasprefix()``, and more than one string was matched
+due to overlapping prefixes. ``.matched()`` returns ``true`` for all
+values of ``select`` if the previous successful operation was
+``.match()``. ``n`` defaults to 0, so the ``n`` parameter can be left
+out if the use of ``select`` is intended.
+
+If ``n`` <= 0 and ``select`` is ``UNIQUE`` or ``EXACT``, then
+``.matched()`` returns ``true`` if the enum's criteria are met;
+otherwise it returns ``false``, and does not fail. This can be used as
+a safeguard for the methods described below, which invoke VCL failure
+if either of these two enums are specified, but their criteria are not
+met.
+
+The other enum values (``FIRST``, ``LAST``, ``SHORTEST`` and
+``LONGEST``) are included for consistency with the other methods, but
+they don't make a relevant distinction. If the prior invocation of
+``.match()`` or ``.hasprefix()`` was successful (returned ``true``),
+then ``.matched()`` returns ``true`` for each of these, since there is
+always an element that meets the criteria. If the prior invocation was
+unsuccessful, ``.matched()`` always returns ``false`` for each of the
+four enums.
 
 ``.matched()`` always returns ``false`` if the most recent
 ``.match()`` or ``.hasprefix()`` call returned ``false``.
 
-``.matched()`` fails and returns ``false`` if:
+``.matched()`` invokes VCL failure if:
 
-* The parameter is out of range -- it is less than 1 or greater than
-  the number of elements in the set.
+* The parameter is out of range -- greater than the number of elements
+  in the set.
 
 * There was no prior invocation of ``.match()`` or ``.hasprefix()`` in
   the same task scope.
 
 Example::
 
-  if (myset.match(req.http.Host)) {
-     if (myset.matched(1)) {
-         call do_if_the_first_element_matched;
-     }
+  if (hosts.match(req.http.Host)) {
+      if (hosts.matched(1)) {
+          call do_if_the_first_host_element_matched;
+      }
+  }
+
+  if (url_prefixes.hasprefix(req.url)) {
+      if (urls.matched(select=UNIQUE)) {
+          call do_if_a_unique_url_prefix_was_matched;
+      }
   }
 
 .. _xset.which():
@@ -621,7 +659,7 @@ If more than one element matched after calling ``.hasprefix()``, the
 index is chosen with the ``select`` parameter, according to the rules
 given above. By default, ``select`` is ``UNIQUE``.
 
-``.which()`` fails and returns 0 if:
+``.which()`` invokes VCL failure if:
 
 * The choice of ``select`` indicates failure, as documented above; that
   is, if ``select`` is ``UNIQUE`` or ``EXACT``, but there was no unique
@@ -660,7 +698,7 @@ The string returned is the same as it was added to the set; even if a
 prior match was case insensitive, and the matched string differs in
 case, the string with the case as added to the set is returned.
 
-``.element()`` fails and returns NULL if the rules for ``n`` and
+``.element()`` invokes VCL failure if the rules for ``n`` and
 ``select`` indicate failure; that is:
 
 * ``n`` is out of range (greater than the number of elements in the
@@ -696,7 +734,7 @@ by ``n`` and ``select``, according to the rules given above; that is,
 it returns the backend that was set via the ``backend`` parameter in
 ``.add()``.
 
-``.backend()`` fails and returns NULL if:
+``.backend()`` invokes VCL failure if:
 
 * The rules for ``n`` and ``select`` indicate failure.
 
@@ -727,7 +765,7 @@ Returns the string set by the ``string`` parameter for the element of
 the set indicated by ``n`` and ``select``, according to the rules
 given above.
 
-``.string()`` fails and returns NULL if:
+``.string()`` invokes VCL failure if:
 
 * The rules for ``n`` and ``select`` indicate failure.
 
@@ -756,25 +794,12 @@ Returns the integer set by the ``integer`` parameter for the element of
 the set indicated by ``n`` and ``select``, according to the rules
 given above.
 
-``.integer()`` invokes VCL failure (see `ERRORS`_) if:
+``.integer()`` invokes VCL failure if:
 
 * The rules for ``n`` and ``select`` indicate failure.
 
 * No integer was set with the ``integer`` parameter in ``.add()``.
 
-Note that VCL failure for ``.integer()`` differs from the failure mode
-for other methods that retrieve data associated with the selected set
-element, such as ``.string()`` and ``.backend()``. Since there is no
-distinguished "error value" for an INT, the VMOD does not return one
-that can be detected in VCL, so that processing could continue without
-failure.
-
-So you may want to check more carefully in VCL for possible errors
-that may cause ``.integer()`` to fail; for example, by checking
-whether ``.nmatches() == 1`` before calling ``.integer()`` with
-``select=UNIQUE`` or ``select=EXACT``, if the previous match operation
-was ``.hasprefix()`` and the set contains overlapping prefixes.
-
 Example::
 
   # Send a synthetic response if the URL has a prefix in the set,
@@ -815,15 +840,17 @@ in native VCL; in particular, it may be limited by the varnishd
 parameters ``pcre_match_limit`` and ``pcre_match_limit_recursion``
 (see varnishd(1)).
 
-``.re_match()`` fails and returns ``false`` if:
+``.re_match()`` invokes VCL failure if:
 
 * The rules for ``n`` and ``select`` indicate failure.
 
 * No regular expression was set with the ``regex`` parameter in
   ``.add()``.
 
-* The regex match fails, for any of the reasons that cause a native
-  match to fail.
+The regex match may fail for any of the reasons that cause a native
+match to fail. In that case, ``.re_match()`` returns ``false``, and a
+log message with tag ``VCL_Error`` is emitted (as for native regeex
+match failures).
 
 Example::
 
@@ -866,15 +893,19 @@ non-overlapping portion of ``str`` that matches the regex with ``sub``
 (possibly with backreferences). This is the same operation as native
 VCL's ``regsuball(str, regex, sub)``.
 
-``.sub()`` fails and returns NULL if:
+``.sub()`` invokes VCL failure if:
 
 * The rules for ``n`` and ``select`` indicate failure.
 
 * No regular expression was set with the ``regex`` parameter in
   ``.add()``.
 
-* The substitution fails for any of the reasons that cause native
-  ``regsub()`` or ``regsuball()`` to fail.
+The substitution may fail for any of the reasons that cause native
+``regsub()`` or ``regsuball()`` to fail. In that case, ``.sub()``
+returns ``str``, and a ``VCL_Error`` message is written to the log, as
+for failures of native match substitution functions. As with the
+native functions, ``str`` is returned if ``regex`` does not match
+``str``.
 
 Example::
 

src/vmod_selector.vcc

@@ -481,8 +481,11 @@ Returns ``true`` if the STRING to be matched has a prefix that is in
 the set. The match is case insensitive if ``case_sensitive`` was set
 to ``false`` in the constructor.
 
-``.hasprefix()`` fails and returns ``false`` under the same conditions
-given for ``.match()`` above.
+``.hasprefix()`` invokes VCL failure under the same conditions given
+for ``.match()`` above. Like ``.match()``, ``.hasprefix()`` returns
+``false`` if the string to be matched is NULL, for example if it is an
+unset header, and a ``Notice`` message is emitted to the log (see
+`LOGGING`_).
 
 Example::
 
@@ -503,9 +506,8 @@ backend context).
 call, it returns the number of strings in the set that are prefixes of
 the string that was matched.
 
-``.nmatches()`` returns 0 and writes an error message to the log if
-there was no prior invocation of ``.match()`` or ``.hasprefix()`` in
-the same task scope.
+``.nmatches()`` invokes VCL failure if there was no prior invocation
+of ``.match()`` or ``.hasprefix()`` in the same task scope.
 
 Example::
 
@@ -526,27 +528,63 @@ $Method BOOL .matched(INT n=0,
 
 After a successful ``.match()`` or ``.hasprefix()`` call for the same
 set object in the same task scope, return ``true`` if the element
-indicated by the INT parameter was matched. The numbering corresponds
-to the order of ``.add()`` invocations in ``vcl_init`` (starting from
-1).
+indicated by the ``n`` and ``select`` parameters was matched, according to
+the rules described above.
+
+For example if ``n`` > 0, ``.matched(n)`` returns ``true`` if and only
+if the ``n``-th element matched. The numbering corresponds to the
+order of ``.add()`` invocations in ``vcl_init`` (starting from 1). The
+``select`` parameter is ignored in this case.
+
+If ``n`` <= 0, the set element is determined by the ``select`` enum.
+In that case, ``.matched()`` returns ``true`` if and only if the
+element indicated by the enum was matched by the previous successful
+match operation. These distinctions are only relevant if the previous
+operation was ``.hasprefix()``, and more than one string was matched
+due to overlapping prefixes. ``.matched()`` returns ``true`` for all
+values of ``select`` if the previous successful operation was
+``.match()``. ``n`` defaults to 0, so the ``n`` parameter can be left
+out if the use of ``select`` is intended.
+
+If ``n`` <= 0 and ``select`` is ``UNIQUE`` or ``EXACT``, then
+``.matched()`` returns ``true`` if the enum's criteria are met;
+otherwise it returns ``false``, and does not fail. This can be used as
+a safeguard for the methods described below, which invoke VCL failure
+if either of these two enums are specified, but their criteria are not
+met.
+
+The other enum values (``FIRST``, ``LAST``, ``SHORTEST`` and
+``LONGEST``) are included for consistency with the other methods, but
+they don't make a relevant distinction. If the prior invocation of
+``.match()`` or ``.hasprefix()`` was successful (returned ``true``),
+then ``.matched()`` returns ``true`` for each of these, since there is
+always an element that meets the criteria. If the prior invocation was
+unsuccessful, ``.matched()`` always returns ``false`` for each of the
+four enums.
 
 ``.matched()`` always returns ``false`` if the most recent
 ``.match()`` or ``.hasprefix()`` call returned ``false``.
 
-``.matched()`` fails and returns ``false`` if:
+``.matched()`` invokes VCL failure if:
 
-* The parameter is out of range -- it is less than 1 or greater than
-  the number of elements in the set.
+* The parameter is out of range -- greater than the number of elements
+  in the set.
 
 * There was no prior invocation of ``.match()`` or ``.hasprefix()`` in
   the same task scope.
 
 Example::
 
-  if (myset.match(req.http.Host)) {
-     if (myset.matched(1)) {
-         call do_if_the_first_element_matched;
-     }
+  if (hosts.match(req.http.Host)) {
+      if (hosts.matched(1)) {
+          call do_if_the_first_host_element_matched;
+      }
+  }
+
+  if (url_prefixes.hasprefix(req.url)) {
+      if (urls.matched(select=UNIQUE)) {
+          call do_if_a_unique_url_prefix_was_matched;
+      }
   }
 
 $Method INT .which(ENUM {UNIQUE, EXACT, FIRST, LAST, SHORTEST, LONGEST}
@@ -564,7 +602,7 @@ If more than one element matched after calling ``.hasprefix()``, the
 index is chosen with the ``select`` parameter, according to the rules
 given above. By default, ``select`` is ``UNIQUE``.
 
-``.which()`` fails and returns 0 if:
+``.which()`` invokes VCL failure if:
 
 * The choice of ``select`` indicates failure, as documented above; that
   is, if ``select`` is ``UNIQUE`` or ``EXACT``, but there was no unique
@@ -595,7 +633,7 @@ The string returned is the same as it was added to the set; even if a
 prior match was case insensitive, and the matched string differs in
 case, the string with the case as added to the set is returned.
 
-``.element()`` fails and returns NULL if the rules for ``n`` and
+``.element()`` invokes VCL failure if the rules for ``n`` and
 ``select`` indicate failure; that is:
 
 * ``n`` is out of range (greater than the number of elements in the
@@ -623,7 +661,7 @@ by ``n`` and ``select``, according to the rules given above; that is,
 it returns the backend that was set via the ``backend`` parameter in
 ``.add()``.
 
-``.backend()`` fails and returns NULL if:
+``.backend()`` invokes VCL failure if:
 
 * The rules for ``n`` and ``select`` indicate failure.
 
@@ -646,7 +684,7 @@ Returns the string set by the ``string`` parameter for the element of
 the set indicated by ``n`` and ``select``, according to the rules
 given above.
 
-``.string()`` fails and returns NULL if:
+``.string()`` invokes VCL failure if:
 
 * The rules for ``n`` and ``select`` indicate failure.
 
@@ -667,25 +705,12 @@ Returns the integer set by the ``integer`` parameter for the element of
 the set indicated by ``n`` and ``select``, according to the rules
 given above.
 
-``.integer()`` invokes VCL failure (see `ERRORS`_) if:
+``.integer()`` invokes VCL failure if:
 
 * The rules for ``n`` and ``select`` indicate failure.
 
 * No integer was set with the ``integer`` parameter in ``.add()``.
 
-Note that VCL failure for ``.integer()`` differs from the failure mode
-for other methods that retrieve data associated with the selected set
-element, such as ``.string()`` and ``.backend()``. Since there is no
-distinguished "error value" for an INT, the VMOD does not return one
-that can be detected in VCL, so that processing could continue without
-failure.
-
-So you may want to check more carefully in VCL for possible errors
-that may cause ``.integer()`` to fail; for example, by checking
-whether ``.nmatches() == 1`` before calling ``.integer()`` with
-``select=UNIQUE`` or ``select=EXACT``, if the previous match operation
-was ``.hasprefix()`` and the set contains overlapping prefixes.
-
 Example::
 
   # Send a synthetic response if the URL has a prefix in the set,
@@ -717,15 +742,17 @@ in native VCL; in particular, it may be limited by the varnishd
 parameters ``pcre_match_limit`` and ``pcre_match_limit_recursion``
 (see varnishd(1)).
 
-``.re_match()`` fails and returns ``false`` if:
+``.re_match()`` invokes VCL failure if:
 
 * The rules for ``n`` and ``select`` indicate failure.
 
 * No regular expression was set with the ``regex`` parameter in
   ``.add()``.
 
-* The regex match fails, for any of the reasons that cause a native
-  match to fail.
+The regex match may fail for any of the reasons that cause a native
+match to fail. In that case, ``.re_match()`` returns ``false``, and a
+log message with tag ``VCL_Error`` is emitted (as for native regeex
+match failures).
 
 Example::
 
@@ -757,15 +784,19 @@ non-overlapping portion of ``str`` that matches the regex with ``sub``
 (possibly with backreferences). This is the same operation as native
 VCL's ``regsuball(str, regex, sub)``.
 
-``.sub()`` fails and returns NULL if:
+``.sub()`` invokes VCL failure if:
 
 * The rules for ``n`` and ``select`` indicate failure.
 
 * No regular expression was set with the ``regex`` parameter in
   ``.add()``.
 
-* The substitution fails for any of the reasons that cause native
-  ``regsub()`` or ``regsuball()`` to fail.
+The substitution may fail for any of the reasons that cause native
+``regsub()`` or ``regsuball()`` to fail. In that case, ``.sub()``
+returns ``str``, and a ``VCL_Error`` message is written to the log, as
+for failures of native match substitution functions. As with the
+native functions, ``str`` is returned if ``regex`` does not match
+``str``.
 
 Example::