Skip to content

L
libvmod-selector
Commit 44080166 authored by Geoff Simmons's avatar Geoff Simmons
Browse files
Options

Document the element parameter.

parent c71e7938
Hide whitespace changes
Inline Side-by-side
Showing with 214 additions and 110 deletions
README.rst
View file @ 44080166
......@@ -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
View file @ 44080166
......@@ -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()``.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment