Commit dda75165 by Geoff Simmons

Document set.which().

parent 47ac7eca
Pipeline #348 skipped
......@@ -50,6 +50,7 @@ import re2 [from "path"] ;
BOOL <obj>.match(STRING)
INT <obj>.nmatches()
BOOL <obj>.matched(INT)
INT <obj>.which([ENUM select])
STRING <obj>.string([INT n,] [ENUM select])
BACKEND <obj>.backend([INT n,] [ENUM select])
......@@ -984,6 +985,63 @@ set.which
INT set.which(ENUM {FIRST,LAST} select=0)
Returns a number indicating which pattern in a set matched in the most
recent invocation of ``.match()`` in the client or backend
context. The number corresponds to the order in which patterns were
added to the set in ``vcl_init``, counting from 1.
If exactly one pattern matched in the most recent ``.match()`` call
(so that ``.nmatches()`` returns 1), then the number for that pattern
is returned. The ``select`` ENUM is ignored in this case, and can be
left out.
If more than one pattern matched in the most recent ``.match()`` call
(``.nmatches()`` > 1), then the ``select`` ENUM determines the integer
that is returned. The values ``FIRST`` and ``LAST`` specify that, of
the patterns that matched, the first or last one added via the
``.add()`` method is chosen, and the number for that pattern is
returned.
``.which()`` fails, returning 0 with a ``VCL_Error`` message in the log,
if:
* ``.match()`` was not called for the set in the current client or
backend transaction, or if the previous call returned ``false``.
* More than one pattern in the set matched in the previous
``.match()`` call, but the ``select`` parameter is not set.
Examples::
sub vcl_init {
new myset = re2.set();
myset.add("foo"); # Pattern 1
myset.add("bar"); # Pattern 2
myset.add("baz"); # Pattern 3
myset.compile();
}
sub vcl_recv {
if (myset.match("bar")) {
# myset.which() returns 2.
}
if (myset.which("foobaz")) {
# myset.which() fails and returns 0, with a log
# message indicating that 2 patterns
# matched.
# myset.which(FIRST) returns 1.
# myset.which(LAST) returns 3.
}
if (myset.match("quux")) {
# ...
}
else {
# myset.which() fails and returns 0, with either or
# no value for the select ENUM, with a log message
# indicating that the previous .match() call was
# unsuccessful.
}
.. _func_set.string:
set.string
......@@ -1016,10 +1074,10 @@ can be used for this purpose with no arguments.
If ``n`` <= 0 and more than one pattern matched in the most recent
``.match()`` call (``.nmatches()`` > 1), then the string returned is
determined by the ``select`` parameter. The values ``FIRST`` and
``LAST`` specify that, of the patterns that matched, the first or last
one added via the ``.add()`` method is chosen, and the string
associated with that pattern is returned.
determined by the ``select`` parameter. As with ``.which()``,
``FIRST`` and ``LAST`` specify that the first or last matching pattern
added via the ``.add()`` method is chosen, and the string associated
with that pattern is returned.
``.string()`` fails, returning NULL with an a ``VCL_Error`` message in
the log, if:
......
......@@ -35,6 +35,7 @@ $Module re2 3 Varnish Module for access to the Google RE2 regular expression eng
BOOL <obj>.match(STRING)
INT <obj>.nmatches()
BOOL <obj>.matched(INT)
INT <obj>.which([ENUM select])
STRING <obj>.string([INT n,] [ENUM select])
BACKEND <obj>.backend([INT n,] [ENUM select])
......@@ -852,6 +853,63 @@ Example::
$Method INT .which(ENUM {FIRST, LAST} select=0)
Returns a number indicating which pattern in a set matched in the most
recent invocation of ``.match()`` in the client or backend
context. The number corresponds to the order in which patterns were
added to the set in ``vcl_init``, counting from 1.
If exactly one pattern matched in the most recent ``.match()`` call
(so that ``.nmatches()`` returns 1), then the number for that pattern
is returned. The ``select`` ENUM is ignored in this case, and can be
left out.
If more than one pattern matched in the most recent ``.match()`` call
(``.nmatches()`` > 1), then the ``select`` ENUM determines the integer
that is returned. The values ``FIRST`` and ``LAST`` specify that, of
the patterns that matched, the first or last one added via the
``.add()`` method is chosen, and the number for that pattern is
returned.
``.which()`` fails, returning 0 with a ``VCL_Error`` message in the log,
if:
* ``.match()`` was not called for the set in the current client or
backend transaction, or if the previous call returned ``false``.
* More than one pattern in the set matched in the previous
``.match()`` call, but the ``select`` parameter is not set.
Examples::
sub vcl_init {
new myset = re2.set();
myset.add("foo"); # Pattern 1
myset.add("bar"); # Pattern 2
myset.add("baz"); # Pattern 3
myset.compile();
}
sub vcl_recv {
if (myset.match("bar")) {
# myset.which() returns 2.
}
if (myset.which("foobaz")) {
# myset.which() fails and returns 0, with a log
# message indicating that 2 patterns
# matched.
# myset.which(FIRST) returns 1.
# myset.which(LAST) returns 3.
}
if (myset.match("quux")) {
# ...
}
else {
# myset.which() fails and returns 0, with either or
# no value for the select ENUM, with a log message
# indicating that the previous .match() call was
# unsuccessful.
}
$Method STRING .string(INT n=0, ENUM {FIRST, LAST} select=0)
Returns the string associated with the `nth` pattern added to the set,
......@@ -877,10 +935,10 @@ can be used for this purpose with no arguments.
If ``n`` <= 0 and more than one pattern matched in the most recent
``.match()`` call (``.nmatches()`` > 1), then the string returned is
determined by the ``select`` parameter. The values ``FIRST`` and
``LAST`` specify that, of the patterns that matched, the first or last
one added via the ``.add()`` method is chosen, and the string
associated with that pattern is returned.
determined by the ``select`` parameter. As with ``.which()``,
``FIRST`` and ``LAST`` specify that the first or last matching pattern
added via the ``.add()`` method is chosen, and the string associated
with that pattern is returned.
``.string()`` fails, returning NULL with an a ``VCL_Error`` message in
the log, if:
......
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