Document the element parameter.

README.rst

@@ -25,7 +25,8 @@ SYNOPSIS
   import selector;
 
   # Set creation
-  new <obj> = selector.set([BOOL case_sensitive])
+  new <obj> = selector.set([BOOL case_sensitive]
+                           [, BOOL allow_overlaps])
   VOID <obj>.add(STRING [, STRING string] [, STRING regex]
 		 [, BACKEND backend] [, INT integer])
   VOID <obj>.compile()
@@ -42,12 +43,13 @@ SYNOPSIS
 
   # Retrieving objects after match
   STRING  <obj>.element([INT n] [, ENUM select])
-  STRING  <obj>.string([INT n]  [, ENUM select])
-  INT     <obj>.integer([INT n] [, ENUM select])
-  BACKEND <obj>.backend([INT n] [, ENUM select])
-  BOOL    <obj>.re_match(STRING [, INT n] [, ENUM select])
+  STRING  <obj>.string([INT n]  [, STRING element] [, ENUM select])
+  INT     <obj>.integer([INT n] [, STRING element] [, ENUM select])
+  BACKEND <obj>.backend([INT n] [, STRING element] [, ENUM select])
+  BOOL    <obj>.re_match(STRING [, INT n] [, STRING element]
+                         [, ENUM select])
   STRING  <obj>.sub(STRING text, STRING rewrite [, BOOL all] [, INT n]
-                    [, ENUM select])
+                    [, STRING element] [, ENUM select])
 
   # VMOD version
   STRING selector.version()
@@ -236,51 +238,74 @@ uses it may be necessary to identify one matching element of the set;
 this is done in particular for the ``.element()``, ``.backend()``,
 ``.string()``, ``.integer()``, ``.re_match()`` and ``.sub()`` methods,
 which retrieve data associated with a specific set element. For such
-cases, the method parameters ``INT n`` and ``ENUM select`` are used to
-choose a matched element.
+cases, the method parameters ``INT n``, ``STRING element`` and ``ENUM
+select`` are used to choose a matched element.
 
 As indicated in the example, elements of a set are implicitly numbered
 in the order in which they were added to the set using the ``.add()``
-method, starting from 1. In all of the following, the ``n`` and
-``select`` parameters for a method call are evaluated as follows:
+method, starting from 1. In all of the following, the ``n``,
+``element`` and ``select`` parameters for a method call are evaluated
+as follows:
 
 * If ``n`` >= 1, then the ``n``-th element of the set is chosen, and
-  the ``select`` parameter has no effect. A method with ``n`` >= 1 can
-  be called in any context, and does not depend on prior match
-  operations. This is essentially a lookup by index.
+  the ``element`` and ``select`` parameters have no effect. A method
+  with ``n`` >= 1 can be called in any context, and does not depend on
+  prior match operations. This is essentially a lookup by index.
 
 * If ``n`` is greater than the number of elements in the set, the
   method invokes VCL failure (see `ERRORS`_).
 
-* If ``n`` <= 0, then the ``select`` parameter is used to choose an
-  element based on the most recent ``.match()`` or ``.hasprefix()``
-  call for the same set object in the same task scope; that is, the
-  most recent call in the same client or backend context. Thus a
-  method call in one of the ``vcl_backend_*`` subroutines refers back
-  to the most recent ``.match()`` or ``.hasprefix()`` invocation in
-  the same backend context.
-
-  ``n`` is 0 by default, so it can be left out of the method call for
-  this purpose.
-
-* If ``n`` <= 0 and neither of ``.match()`` or ``.hasprefix()`` has
-  been called for the same set object in the same task scope, or if
-  the most recent call resulted in a failed match, then the method
-  invokes VCL failure.
-
-* When ``n`` <= 0 after a successful ``.match()`` call, then for any
-  value of ``select``, the element chosen is the one that matched.
-
-* When ``n`` <= 0 after a successful ``.hasprefix()`` call, then the
-  value of ``select`` determines the element chosen, as follows:
+* If ``n`` <= 0 and the ``element`` parameter is set, then the VMOD
+  searches for the string specified by ``element``, in the same way
+  that the ``.match()`` method is executed. This is in essence a
+  lookup in an associative array.
+
+  If ``element`` is set but the lookup fails, that is if there is no
+  such element in the set, then VCL failure is invoked. If the lookup
+  for the ``element`` succeeds, then the successful match establishes
+  a match context for subsequent code. That means that the rules
+  presently described can be applied again, as if ``.match()`` had
+  returned ``true`` for the ``element`` (internally, that is in fact
+  what happens).
+
+  The internal match against ``element`` is case sensitive if and only
+  if the ``case_sensitive`` flag was ``true`` in the set constructor
+  (this is the default).
+
+  ``n`` is 0 by default, so it can be left out of the method call when
+  ``element`` is set.
+
+* If ``n`` <= 0 and ``element`` is unset, then the ``select``
+  parameter is used to choose an element based on the most recent
+  ``.match()`` or ``.hasprefix()`` call for the same set object in the
+  same task scope; that is, the most recent call in the same client or
+  backend context. Thus a method call in one of the ``vcl_backend_*``
+  subroutines refers back to the most recent ``.match()`` or
+  ``.hasprefix()`` invocation in the same backend context.
+
+  By default, ``n`` is 0 and ``element`` is unset, so both of them can
+  be left out of the call to use ``select``.
+
+* If ``n`` <= 0 and ``element`` is unset, and neither of ``.match()``
+  or ``.hasprefix()`` has been called for the same set object in the
+  same task scope, or if the most recent call resulted in a failed
+  match, then the method invokes VCL failure.
+
+* When ``n`` <= 0 and ``element`` is unset after a successful
+  ``.match()`` call, then for any value of ``select``, the element
+  chosen is the one that matched.
+
+* When ``n`` <= 0 and ``element`` is unset after a successful
+  ``.hasprefix()`` call, then the value of ``select`` determines the
+  element chosen, as follows:
 
   * ``UNIQUE`` (default): if exactly one element of the set matched,
     choose that element. The method invokes VCL failure in this case
     if more than one element matched.
 
     Since the defaults for ``n`` and ``select`` are 0 and ``UNIQUE``,
-    ``select=UNIQUE`` is in effect if both parameters are left out of
-    the method call.
+    and ``element`` is unset by default, ``select=UNIQUE`` is in
+    effect if all three parameters are left out of the method call.
 
   * ``EXACT``: if one of the elements in the set matched exactly (even
     if other prefixes in the set matched as well), choose that
@@ -325,6 +350,33 @@ or the longest match, and so on::
   # bar_backend for /foo/bar/quux
   # foo_backend for /foo/quux
 
+To re-state the rules more informally:
+
+* Use only one of ``n``, ``element`` or ``select`` to select a string
+  in the set.
+
+  * If ``n`` > 0, use ``n``. ``n`` = 0 by default.
+
+  * Otherwise if ``element`` is set, use ``element``. ``element`` is
+    unset by default.
+
+  * Otherwise use ``select``, default ``UNIQUE``.
+
+* ``n`` is a lookup by numeric index, as implied by the order of
+  ``.add()`` in ``vcl_init``.
+
+* ``element`` is an associative array lookup by string.
+
+* ``select`` refers back to the previous invocation of ``.match()`` or
+  ``.hasprefix()``.
+
+  * The value of ``select`` is irrelevant (and can just as well be
+    left out) if the prior invocation was ``.match()``, or if it was
+    ``.hasprefix()`` and exactly one string was found (which is always
+    the case if strings in the set have no common
+    prefixes). ``select`` is meant to pick an element when
+    ``.hasprefix()`` finds more than one string.
+
 .. _selector.set():
 
 new xset = selector.set(BOOL case_sensitive, BOOL allow_overlaps)
@@ -732,13 +784,13 @@ BACKEND xset.backend(INT n, STRING element, ENUM select)
       )
 
 Returns the backend associated with the element of the set indicated
-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()``.
+by ``n``, ``element`` and ``select``, according to the rules given
+above; that is, it returns the backend that was set via the
+``backend`` parameter in ``.add()``.
 
 ``.backend()`` invokes VCL failure if:
 
-* The rules for ``n`` and ``select`` indicate failure.
+* The rules for ``n``, ``element`` and ``select`` indicate failure.
 
 * No backend was set with the ``backend`` parameter in the ``.add()``
   call corresponding to the selected element.
@@ -765,12 +817,12 @@ STRING xset.string(INT n, STRING element, ENUM select)
       )
 
 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.
+the set indicated by ``n``, ``element`` and ``select``, according to
+the rules given above.
 
 ``.string()`` invokes VCL failure if:
 
-* The rules for ``n`` and ``select`` indicate failure.
+* The rules for ``n``, ``element`` and ``select`` indicate failure.
 
 * No string was set with the ``string`` parameter in ``.add()``.
 
@@ -794,13 +846,13 @@ INT xset.integer(INT n, STRING element, ENUM select)
             ENUM {UNIQUE, EXACT, FIRST, LAST, SHORTEST, LONGEST} select=UNIQUE
       )
 
-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.
+Returns the integer set by the ``integer`` parameter for the element
+of the set indicated by ``n``, ``element`` and ``select``, according
+to the rules given above.
 
 ``.integer()`` invokes VCL failure if:
 
-* The rules for ``n`` and ``select`` indicate failure.
+* The rules for ``n``, ``element`` and ``select`` indicate failure.
 
 * No integer was set with the ``integer`` parameter in ``.add()``.
 
@@ -831,10 +883,10 @@ BOOL xset.re_match(STRING subject, INT n, STRING element, ENUM select)
       )
 
 Using the regular expression set by the ``regex`` parameter for the
-element of the set indicated by ``n`` and ``select``, return the
-result of matching the regex against ``subject``. The regex match is
-the same operation performed for the native VCL ``~`` operator, see
-vcl(7).
+element of the set indicated by ``n``, ``element`` and ``select``,
+return the result of matching the regex against ``subject``. The regex
+match is the same operation performed for the native VCL ``~``
+operator, see vcl(7).
 
 In other words, this method can be used to perform a second match with
 the saved regular expression, after matching a fixed string against
@@ -847,7 +899,7 @@ parameters ``pcre_match_limit`` and ``pcre_match_limit_recursion``
 
 ``.re_match()`` invokes VCL failure if:
 
-* The rules for ``n`` and ``select`` indicate failure.
+* The rules for ``n``, ``element`` and ``select`` indicate failure.
 
 * No regular expression was set with the ``regex`` parameter in
   ``.add()``.
@@ -884,8 +936,8 @@ STRING xset.sub(STRING str, STRING sub, BOOL all, INT n, STRING element, ENUM se
       )
 
 Using the regular expression set by the ``regex`` parameter for the
-element of the set indicated by ``n`` and ``select``, return the
-result of a substitution using ``str`` and ``sub``.
+element of the set indicated by ``n``, ``element`` and ``select``,
+return the result of a substitution using ``str`` and ``sub``.
 
 If ``all`` is ``false``, then return the result of replacing the first
 portion of ``str`` that matches the regex with ``sub``. ``sub`` may
@@ -901,7 +953,7 @@ VCL's ``regsuball(str, regex, sub)``.
 
 ``.sub()`` invokes VCL failure if:
 
-* The rules for ``n`` and ``select`` indicate failure.
+* The rules for ``n``, ``element`` and ``select`` indicate failure.
 
 * No regular expression was set with the ``regex`` parameter in
   ``.add()``.

src/vmod_selector.vcc

@@ -21,7 +21,8 @@ SYNOPSIS
   import selector;
 
   # Set creation
-  new <obj> = selector.set([BOOL case_sensitive])
+  new <obj> = selector.set([BOOL case_sensitive]
+                           [, BOOL allow_overlaps])
   VOID <obj>.add(STRING [, STRING string] [, STRING regex]
 		 [, BACKEND backend] [, INT integer])
   VOID <obj>.compile()
@@ -38,12 +39,13 @@ SYNOPSIS
 
   # Retrieving objects after match
   STRING  <obj>.element([INT n] [, ENUM select])
-  STRING  <obj>.string([INT n]  [, ENUM select])
-  INT     <obj>.integer([INT n] [, ENUM select])
-  BACKEND <obj>.backend([INT n] [, ENUM select])
-  BOOL    <obj>.re_match(STRING [, INT n] [, ENUM select])
+  STRING  <obj>.string([INT n]  [, STRING element] [, ENUM select])
+  INT     <obj>.integer([INT n] [, STRING element] [, ENUM select])
+  BACKEND <obj>.backend([INT n] [, STRING element] [, ENUM select])
+  BOOL    <obj>.re_match(STRING [, INT n] [, STRING element]
+                         [, ENUM select])
   STRING  <obj>.sub(STRING text, STRING rewrite [, BOOL all] [, INT n]
-                    [, ENUM select])
+                    [, STRING element] [, ENUM select])
 
   # VMOD version
   STRING selector.version()
@@ -232,51 +234,74 @@ uses it may be necessary to identify one matching element of the set;
 this is done in particular for the ``.element()``, ``.backend()``,
 ``.string()``, ``.integer()``, ``.re_match()`` and ``.sub()`` methods,
 which retrieve data associated with a specific set element. For such
-cases, the method parameters ``INT n`` and ``ENUM select`` are used to
-choose a matched element.
+cases, the method parameters ``INT n``, ``STRING element`` and ``ENUM
+select`` are used to choose a matched element.
 
 As indicated in the example, elements of a set are implicitly numbered
 in the order in which they were added to the set using the ``.add()``
-method, starting from 1. In all of the following, the ``n`` and
-``select`` parameters for a method call are evaluated as follows:
+method, starting from 1. In all of the following, the ``n``,
+``element`` and ``select`` parameters for a method call are evaluated
+as follows:
 
 * If ``n`` >= 1, then the ``n``-th element of the set is chosen, and
-  the ``select`` parameter has no effect. A method with ``n`` >= 1 can
-  be called in any context, and does not depend on prior match
-  operations. This is essentially a lookup by index.
+  the ``element`` and ``select`` parameters have no effect. A method
+  with ``n`` >= 1 can be called in any context, and does not depend on
+  prior match operations. This is essentially a lookup by index.
 
 * If ``n`` is greater than the number of elements in the set, the
   method invokes VCL failure (see `ERRORS`_).
 
-* If ``n`` <= 0, then the ``select`` parameter is used to choose an
-  element based on the most recent ``.match()`` or ``.hasprefix()``
-  call for the same set object in the same task scope; that is, the
-  most recent call in the same client or backend context. Thus a
-  method call in one of the ``vcl_backend_*`` subroutines refers back
-  to the most recent ``.match()`` or ``.hasprefix()`` invocation in
-  the same backend context.
-
-  ``n`` is 0 by default, so it can be left out of the method call for
-  this purpose.
-
-* If ``n`` <= 0 and neither of ``.match()`` or ``.hasprefix()`` has
-  been called for the same set object in the same task scope, or if
-  the most recent call resulted in a failed match, then the method
-  invokes VCL failure.
-
-* When ``n`` <= 0 after a successful ``.match()`` call, then for any
-  value of ``select``, the element chosen is the one that matched.
-
-* When ``n`` <= 0 after a successful ``.hasprefix()`` call, then the
-  value of ``select`` determines the element chosen, as follows:
+* If ``n`` <= 0 and the ``element`` parameter is set, then the VMOD
+  searches for the string specified by ``element``, in the same way
+  that the ``.match()`` method is executed. This is in essence a
+  lookup in an associative array.
+
+  If ``element`` is set but the lookup fails, that is if there is no
+  such element in the set, then VCL failure is invoked. If the lookup
+  for the ``element`` succeeds, then the successful match establishes
+  a match context for subsequent code. That means that the rules
+  presently described can be applied again, as if ``.match()`` had
+  returned ``true`` for the ``element`` (internally, that is in fact
+  what happens).
+
+  The internal match against ``element`` is case sensitive if and only
+  if the ``case_sensitive`` flag was ``true`` in the set constructor
+  (this is the default).
+
+  ``n`` is 0 by default, so it can be left out of the method call when
+  ``element`` is set.
+
+* If ``n`` <= 0 and ``element`` is unset, then the ``select``
+  parameter is used to choose an element based on the most recent
+  ``.match()`` or ``.hasprefix()`` call for the same set object in the
+  same task scope; that is, the most recent call in the same client or
+  backend context. Thus a method call in one of the ``vcl_backend_*``
+  subroutines refers back to the most recent ``.match()`` or
+  ``.hasprefix()`` invocation in the same backend context.
+
+  By default, ``n`` is 0 and ``element`` is unset, so both of them can
+  be left out of the call to use ``select``.
+
+* If ``n`` <= 0 and ``element`` is unset, and neither of ``.match()``
+  or ``.hasprefix()`` has been called for the same set object in the
+  same task scope, or if the most recent call resulted in a failed
+  match, then the method invokes VCL failure.
+
+* When ``n`` <= 0 and ``element`` is unset after a successful
+  ``.match()`` call, then for any value of ``select``, the element
+  chosen is the one that matched.
+
+* When ``n`` <= 0 and ``element`` is unset after a successful
+  ``.hasprefix()`` call, then the value of ``select`` determines the
+  element chosen, as follows:
 
   * ``UNIQUE`` (default): if exactly one element of the set matched,
     choose that element. The method invokes VCL failure in this case
     if more than one element matched.
 
     Since the defaults for ``n`` and ``select`` are 0 and ``UNIQUE``,
-    ``select=UNIQUE`` is in effect if both parameters are left out of
-    the method call.
+    and ``element`` is unset by default, ``select=UNIQUE`` is in
+    effect if all three parameters are left out of the method call.
 
   * ``EXACT``: if one of the elements in the set matched exactly (even
     if other prefixes in the set matched as well), choose that
@@ -321,6 +346,33 @@ or the longest match, and so on::
   # bar_backend for /foo/bar/quux
   # foo_backend for /foo/quux
 
+To re-state the rules more informally:
+
+* Use only one of ``n``, ``element`` or ``select`` to select a string
+  in the set.
+
+  * If ``n`` > 0, use ``n``. ``n`` = 0 by default.
+
+  * Otherwise if ``element`` is set, use ``element``. ``element`` is
+    unset by default.
+
+  * Otherwise use ``select``, default ``UNIQUE``.
+
+* ``n`` is a lookup by numeric index, as implied by the order of
+  ``.add()`` in ``vcl_init``.
+
+* ``element`` is an associative array lookup by string.
+
+* ``select`` refers back to the previous invocation of ``.match()`` or
+  ``.hasprefix()``.
+
+  * The value of ``select`` is irrelevant (and can just as well be
+    left out) if the prior invocation was ``.match()``, or if it was
+    ``.hasprefix()`` and exactly one string was found (which is always
+    the case if strings in the set have no common
+    prefixes). ``select`` is meant to pick an element when
+    ``.hasprefix()`` finds more than one string.
+
 $Object set(BOOL case_sensitive=1, BOOL allow_overlaps=1)
 
 Create a set object.
@@ -658,13 +710,13 @@ $Method BACKEND .backend(INT n=0, STRING element=0,
 			 select=UNIQUE)
 
 Returns the backend associated with the element of the set indicated
-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()``.
+by ``n``, ``element`` and ``select``, according to the rules given
+above; that is, it returns the backend that was set via the
+``backend`` parameter in ``.add()``.
 
 ``.backend()`` invokes VCL failure if:
 
-* The rules for ``n`` and ``select`` indicate failure.
+* The rules for ``n``, ``element`` and ``select`` indicate failure.
 
 * No backend was set with the ``backend`` parameter in the ``.add()``
   call corresponding to the selected element.
@@ -682,12 +734,12 @@ $Method STRING .string(INT n=0, STRING element=0,
 		       select=UNIQUE)
 
 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.
+the set indicated by ``n``, ``element`` and ``select``, according to
+the rules given above.
 
 ``.string()`` invokes VCL failure if:
 
-* The rules for ``n`` and ``select`` indicate failure.
+* The rules for ``n``, ``element`` and ``select`` indicate failure.
 
 * No string was set with the ``string`` parameter in ``.add()``.
 
@@ -702,13 +754,13 @@ $Method INT .integer(INT n=0, STRING element=0,
                      ENUM {UNIQUE, EXACT, FIRST, LAST, SHORTEST, LONGEST}
 		     select=UNIQUE)
 
-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.
+Returns the integer set by the ``integer`` parameter for the element
+of the set indicated by ``n``, ``element`` and ``select``, according
+to the rules given above.
 
 ``.integer()`` invokes VCL failure if:
 
-* The rules for ``n`` and ``select`` indicate failure.
+* The rules for ``n``, ``element`` and ``select`` indicate failure.
 
 * No integer was set with the ``integer`` parameter in ``.add()``.
 
@@ -729,10 +781,10 @@ $Method BOOL .re_match(STRING subject, INT n=0, STRING element=0,
 		       select=UNIQUE)
 
 Using the regular expression set by the ``regex`` parameter for the
-element of the set indicated by ``n`` and ``select``, return the
-result of matching the regex against ``subject``. The regex match is
-the same operation performed for the native VCL ``~`` operator, see
-vcl(7).
+element of the set indicated by ``n``, ``element`` and ``select``,
+return the result of matching the regex against ``subject``. The regex
+match is the same operation performed for the native VCL ``~``
+operator, see vcl(7).
 
 In other words, this method can be used to perform a second match with
 the saved regular expression, after matching a fixed string against
@@ -745,7 +797,7 @@ parameters ``pcre_match_limit`` and ``pcre_match_limit_recursion``
 
 ``.re_match()`` invokes VCL failure if:
 
-* The rules for ``n`` and ``select`` indicate failure.
+* The rules for ``n``, ``element`` and ``select`` indicate failure.
 
 * No regular expression was set with the ``regex`` parameter in
   ``.add()``.
@@ -771,8 +823,8 @@ $Method STRING .sub(STRING str, STRING sub, BOOL all=0, INT n=0,
 		    select=UNIQUE)
 
 Using the regular expression set by the ``regex`` parameter for the
-element of the set indicated by ``n`` and ``select``, return the
-result of a substitution using ``str`` and ``sub``.
+element of the set indicated by ``n``, ``element`` and ``select``,
+return the result of a substitution using ``str`` and ``sub``.
 
 If ``all`` is ``false``, then return the result of replacing the first
 portion of ``str`` that matches the regex with ``sub``. ``sub`` may
@@ -788,7 +840,7 @@ VCL's ``regsuball(str, regex, sub)``.
 
 ``.sub()`` invokes VCL failure if:
 
-* The rules for ``n`` and ``select`` indicate failure.
+* The rules for ``n``, ``element`` and ``select`` indicate failure.
 
 * No regular expression was set with the ``regex`` parameter in
   ``.add()``.