Skip to content

L
libvmod-re2
Commit 01a33923 authored by Geoff Simmons's avatar Geoff Simmons
Browse files
Options

Document the set.sub() method.

parent 9d412a66
Hide whitespace changes
Inline Side-by-side
Showing with 299 additions and 129 deletions
README.rst
View file @ 01a33923
......@@ -39,9 +39,12 @@ import re2 [from "path"] ;
BOOL re2.match(STRING pattern, STRING subject [, <regex options>])
STRING re2.backref(INT ref)
STRING re2.namedref(STRING name)
STRING re2.sub(STRING pattern, STRING text, STRING rewrite [, <regex options>])
STRING re2.suball(STRING pattern, STRING text, STRING rewrite [, <regex options>])
STRING re2.extract(STRING pattern, STRING text, STRING rewrite [, <regex options>])
STRING re2.sub(STRING pattern, STRING text, STRING rewrite
[, <regex options>])
STRING re2.suball(STRING pattern, STRING text, STRING rewrite
[, <regex options>])
STRING re2.extract(STRING pattern, STRING text, STRING rewrite
[, <regex options>])
# set object interface
new OBJECT = re2.set([ENUM anchor] [, <regex options>])
......@@ -53,6 +56,7 @@ import re2 [from "path"] ;
INT <obj>.which([ENUM select])
STRING <obj>.string([INT n,] [ENUM select])
BACKEND <obj>.backend([INT n,] [ENUM select])
STRING <obj>.sub(STRING text, STRING rewrite [, INT n] [, ENUM select])
# VMOD version
STRING re2.version()
......@@ -300,9 +304,9 @@ CONTENTS
========
* 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)
* BOOL match(STRING, STRING, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
* STRING backref(INT, STRING)
* STRING namedref(STRING, 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)
......@@ -578,7 +582,7 @@ match
::
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)
BOOL match(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)
Like the ``regex.match()`` method, return ``true`` if ``pattern``
matches ``subject``, where ``pattern`` is compiled with the given
......@@ -601,7 +605,7 @@ backref
::
STRING backref(PRIV_TASK, INT ref, STRING fallback="**BACKREF FUNCTION FAILED**")
STRING backref(INT ref, STRING fallback="**BACKREF FUNCTION FAILED**")
Returns the `nth` captured subexpression from the most recent
successful call of the ``match()`` function in the current client or
......@@ -640,7 +644,7 @@ namedref
::
STRING namedref(PRIV_TASK, STRING name, STRING fallback="**NAMEDREF FUNCTION FAILED**")
STRING namedref(STRING name, STRING fallback="**NAMEDREF FUNCTION FAILED**")
Returns the captured subexpression designated by ``name`` from the
most recent successful call to the ``match()`` function in the current
......@@ -817,6 +821,25 @@ pattern after it matches successfully. ``string`` and ``backend``
default to NULL; that is; by default the pattern is not associated
with any such value.
If ``save`` is true, then the given pattern is compiled and saved as a
``regex`` object, just as if the ``regex`` constructor described above
is invoked. This object is stored internally in the ``set`` object as
an independent matcher, separate from "compound" pattern formed by the
set as an alternation of the patterns added to it. By default,
``save`` is **false**.
When the ``.match()`` method on the set is successful, and one of the
patterns that matched is associated with a saved internal ``regex``
object, then that object may be used for subsequent method invocations
such as ``.sub()`` on the set object, whose meanings are the same as
documented above for ``regex`` objects. Details are described below.
When an internal ``regex`` object is saved (i.e. when ``save`` is
true), it is compiled with the same options that were provided to the
set object in the constructor. The ``never_capture`` option can also
be set to false for the individual regex, even though it is implicitly
set to true for the full set object (default is false).
``.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
......@@ -828,8 +851,9 @@ finally call ``.compile()`` when you're done.
When the ``.matched(INT)`` method is called after a successful match,
the numbering corresponds to the order in which patterns were added.
The same is true of the INT arguments that may be given for the
``.string()`` or ``.backend()`` methods.
The same is true of the INT arguments that may be given for methods
such as ``.string()``, ``.backend()`` or ``.sub()``, as described
below.
Example::
......@@ -1042,15 +1066,6 @@ Examples::
# unsuccessful.
}
.. _func_set.sub:
set.sub
-------
::
STRING set.sub(STRING text, STRING rewrite, STRING fallback="**SUB METHOD FAILED**", INT n=0, ENUM {FIRST,LAST} select=0)
.. _func_set.string:
set.string
......@@ -1062,48 +1077,59 @@ set.string
Returns the string associated with the `nth` pattern added to the set,
or with the pattern in the set that matched in the most recent call to
``.match()`` in the same task scope (client or backend context).
If ``n`` > 0, then return the string associated with the `nth` pattern
added to the set with the ``string`` parameter of the ``.add()``
method, counting from 1. This will return the `nth` string in any
context, regardless of whether ``.match()`` was called previously, or
whether a previous call returned ``true`` or ``false``.
If ``n`` <= 0, then return the string associated with a pattern in the
set that matched successfully in the most recent call to ``.match()``
in the task scope. Since ``n`` is 0 by default, ``n`` can be left out
for this purpose.
If ``n`` <= 0 and exactly one pattern in the set matched in the most
recent invocation of ``.match()`` (and hence ``.nmatches()`` returns
1), then the string associated with that pattern is returned. The
``select`` parameter is ignored in this case. Thus ``.string()``
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. 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.
``.match()`` in the same task scope (client or backend context). The
string set with the ``string`` parameter of the ``.add()`` method
during ``vcl_init`` is returned.
The pattern is identified with the parameters ``n`` and ``select``
according to these rules, which also hold for all further ``set``
methods documented in the following.
* If ``n`` > 0, then select the `nth` pattern added to the set with
the ``.add()`` method, counting from 1. This identifies the `nth`
pattern in any context, regardless of whether ``.match()`` was
called previously, or whether a previous call returned ``true`` or
``false``. The ``select`` parameter is ignored in this case.
* If ``n`` <= 0, then select a pattern in the set that matched
successfully in the most recent call to ``.match()`` in the same
task scope. Since ``n`` is 0 by default, ``n`` can be left out for
this purpose.
* If ``n`` <= 0 and exactly one pattern in the set matched in the most
recent invocation of ``.match()`` (and hence ``.nmatches()`` returns
1), then select that pattern. The ``select`` parameter is ignored in
this case. So when exactly one pattern in the set matched, both
``n`` and ``select`` can be left out.
* If ``n`` <= 0 and more than one pattern matched in the most recent
``.match()`` call (``.nmatches()`` > 1), then the selection of a
pattern is determined by the ``select`` parameter. As with
``.which()``, ``FIRST`` and ``LAST`` specify the first or last
matching pattern added via the ``.add()`` method.
For the pattern selected by these rules, return the string that was
set with the ``string`` parameter in the ``.add()`` method that added
the pattern to the set.
``.string()`` fails, returning NULL with an a ``VCL_Error`` message in
the log, if:
* ``n`` is greater than the number of patterns in the set.
* The values of ``n`` and ``select`` are invalid:
* ``n`` is greater than the number of patterns in the set.
* ``n`` <= 0 (or left to the default), but ``.match()`` was not called
earlier in the same task scope (client or backend context).
* ``n`` <= 0 (or left to the default), but ``.match()`` was not
called earlier in the same task scope (client or backend context).
* ``n`` <= 0, but the previous ``.match()`` call returned ``false``.
* ``n`` <= 0, but the previous ``.match()`` call returned ``false``.
* ``n`` <= 0 and no value is given for the ``select`` ENUM, but more
than one pattern matched in the previous ``.match()`` call.
* ``n`` <= 0 and no value is given for the ``select`` ENUM, but more
than one pattern matched in the previous ``.match()`` call.
* A pattern from the set is selected as described above, but no string
was associated with that pattern; that is, the ``string`` parameter
was not set in the ``.add()`` call that added the pattern.
* No string was associated with the pattern selected by ``n`` and
``select``; that is, the ``string`` parameter was not set in the
``.add()`` call that added the pattern.
Examples::
......@@ -1187,25 +1213,13 @@ call to ``.match()`` in the same task scope (client or backend
context).
The rules for selecting a pattern from the set and its associated
backend are the same as for ``.string()`` above:
* If ``n`` > 0, then return the string associated with the `nth`
pattern added to the set with the ``backend`` parameter of the
``.add()`` method, counting from 1 (independent of any previous
``.match()`` call).
* If ``n`` <= 0 (or left to the default) and exactly one pattern in
the set matched in the most recent invocation of ``.match()``
(``.nmatches()`` == 1), then return the backend associated with that
pattern (ignoring the value of ``select``).
* If ``n`` <= 0 and ``.nmatches()`` > 1, then return the backend
associated with the first or last matching pattern in the set
as determined by the ``select`` parameter.
backend based on ``n`` and ``select`` are the same as described above
for ``.string()``.
``.backend()`` fails, returning NULL with an a ``VCL_Error`` message
in the log, under the same conditions described for ``.string()``
above.
above -- ``n`` and ``select`` are invalid, or no backend was
associated with the selected pattern with the ``.add()`` method.
Example::
......@@ -1237,6 +1251,77 @@ Example::
}
}
.. _func_set.sub:
set.sub
-------
::
STRING set.sub(STRING text, STRING rewrite, STRING fallback="**SUB METHOD FAILED**", INT n=0, ENUM {FIRST,LAST} select=0)
Returns the result of the method call ``.sub(text, rewrite, fallback)``,
as documented above for the ``regex`` interface, invoked on the `nth`
pattern added to the set, or on the pattern in the set that matched in
the most recent call to ``.match()`` in the same task scope.
``.sub()`` requires that the pattern it identifies was saved as an
internal ``regex`` object, by setting ``save`` to true when it was
added with the ``.add()`` method.
The associated pattern is determined by ``n`` and ``select`` according
to the rules given above. If an internal ``regex`` object was saved
for that pattern, then the result of the ``.sub()`` method invoked on
that object is returned.
``.sub()`` fails, returning NULL with a ``VCL_Error`` message in the
log, if:
* The values of ``n`` and ``select`` are invalid, according to the
rules given above.
* ``save`` was false in the ``.add()`` method for the pattern
identified by ``n`` and ``select``; that is, no internal ``regex``
object was saved on which the ``.sub()`` method could have been
invoked.
* The ``.sub()`` method invoked on the ``regex`` object fails for any
of the reasons described for ``regex.sub()``.
Examples::
# Generate synthethic redirect responses on URLs that match a set of
# patterns, rewriting the URL according to the matched pattern.
# In this example, we set the new URL in the redirect location to
# the path that comes after the prefix of the original req.url.
sub vcl_init {
new matcher = re2.set(anchor=start);
matcher.add("/foo/(.*)", save=true);
matcher.add("/bar/(.*)", save=true);
matcher.add("/baz/(.*)", save=true);
matcher.compile();
}
sub vcl_recv {
if (matcher.match(req.url)) {
if (matcher.nmatches() != 1) {
return(fail);
}
return(synth(1301));
}
}
sub vcl_synth {
if (resp.status == 1301) {
# matcher.sub() rewrites the URL to the subpath after the
# original prefix.
set resp.http.Location
= "http://www.otherdomain.org" + matcher.sub(req.url, "/\1");
return(deliver);
}
}
.. _func_version:
version
......
src/vmod_re2.vcc
View file @ 01a33923
......@@ -24,9 +24,12 @@ $Module re2 3 Varnish Module for access to the Google RE2 regular expression eng
BOOL re2.match(STRING pattern, STRING subject [, <regex options>])
STRING re2.backref(INT ref)
STRING re2.namedref(STRING name)
STRING re2.sub(STRING pattern, STRING text, STRING rewrite [, <regex options>])
STRING re2.suball(STRING pattern, STRING text, STRING rewrite [, <regex options>])
STRING re2.extract(STRING pattern, STRING text, STRING rewrite [, <regex options>])
STRING re2.sub(STRING pattern, STRING text, STRING rewrite
[, <regex options>])
STRING re2.suball(STRING pattern, STRING text, STRING rewrite
[, <regex options>])
STRING re2.extract(STRING pattern, STRING text, STRING rewrite
[, <regex options>])
# set object interface
new OBJECT = re2.set([ENUM anchor] [, <regex options>])
......@@ -38,6 +41,7 @@ $Module re2 3 Varnish Module for access to the Google RE2 regular expression eng
INT <obj>.which([ENUM select])
STRING <obj>.string([INT n,] [ENUM select])
BACKEND <obj>.backend([INT n,] [ENUM select])
STRING <obj>.sub(STRING text, STRING rewrite [, INT n] [, ENUM select])
# VMOD version
STRING re2.version()
......@@ -721,6 +725,25 @@ pattern after it matches successfully. ``string`` and ``backend``
default to NULL; that is; by default the pattern is not associated
with any such value.
If ``save`` is true, then the given pattern is compiled and saved as a
``regex`` object, just as if the ``regex`` constructor described above
is invoked. This object is stored internally in the ``set`` object as
an independent matcher, separate from "compound" pattern formed by the
set as an alternation of the patterns added to it. By default,
``save`` is **false**.
When the ``.match()`` method on the set is successful, and one of the
patterns that matched is associated with a saved internal ``regex``
object, then that object may be used for subsequent method invocations
such as ``.sub()`` on the set object, whose meanings are the same as
documented above for ``regex`` objects. Details are described below.
When an internal ``regex`` object is saved (i.e. when ``save`` is
true), it is compiled with the same options that were provided to the
set object in the constructor. The ``never_capture`` option can also
be set to false for the individual regex, even though it is implicitly
set to true for the full set object (default is false).
``.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
......@@ -732,8 +755,9 @@ finally call ``.compile()`` when you're done.
When the ``.matched(INT)`` method is called after a successful match,
the numbering corresponds to the order in which patterns were added.
The same is true of the INT arguments that may be given for the
``.string()`` or ``.backend()`` methods.
The same is true of the INT arguments that may be given for methods
such as ``.string()``, ``.backend()`` or ``.sub()``, as described
below.
Example::
......@@ -911,56 +935,63 @@ Examples::
# unsuccessful.
}
$Method STRING .sub(STRING text, STRING rewrite,
STRING fallback="**SUB METHOD FAILED**",
INT n=0, ENUM {FIRST, LAST} select=0)
$Method STRING .string(INT n=0, ENUM {FIRST, LAST} select=0)
Returns the string associated with the `nth` pattern added to the set,
or with the pattern in the set that matched in the most recent call to
``.match()`` in the same task scope (client or backend context).
If ``n`` > 0, then return the string associated with the `nth` pattern
added to the set with the ``string`` parameter of the ``.add()``
method, counting from 1. This will return the `nth` string in any
context, regardless of whether ``.match()`` was called previously, or
whether a previous call returned ``true`` or ``false``.
If ``n`` <= 0, then return the string associated with a pattern in the
set that matched successfully in the most recent call to ``.match()``
in the task scope. Since ``n`` is 0 by default, ``n`` can be left out
for this purpose.
If ``n`` <= 0 and exactly one pattern in the set matched in the most
recent invocation of ``.match()`` (and hence ``.nmatches()`` returns
1), then the string associated with that pattern is returned. The
``select`` parameter is ignored in this case. Thus ``.string()``
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. 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.
``.match()`` in the same task scope (client or backend context). The
string set with the ``string`` parameter of the ``.add()`` method
during ``vcl_init`` is returned.
The pattern is identified with the parameters ``n`` and ``select``
according to these rules, which also hold for all further ``set``
methods documented in the following.
* If ``n`` > 0, then select the `nth` pattern added to the set with
the ``.add()`` method, counting from 1. This identifies the `nth`
pattern in any context, regardless of whether ``.match()`` was
called previously, or whether a previous call returned ``true`` or
``false``. The ``select`` parameter is ignored in this case.
* If ``n`` <= 0, then select a pattern in the set that matched
successfully in the most recent call to ``.match()`` in the same
task scope. Since ``n`` is 0 by default, ``n`` can be left out for
this purpose.
* If ``n`` <= 0 and exactly one pattern in the set matched in the most
recent invocation of ``.match()`` (and hence ``.nmatches()`` returns
1), then select that pattern. The ``select`` parameter is ignored in
this case. So when exactly one pattern in the set matched, both
``n`` and ``select`` can be left out.
* If ``n`` <= 0 and more than one pattern matched in the most recent
``.match()`` call (``.nmatches()`` > 1), then the selection of a
pattern is determined by the ``select`` parameter. As with
``.which()``, ``FIRST`` and ``LAST`` specify the first or last
matching pattern added via the ``.add()`` method.
For the pattern selected by these rules, return the string that was
set with the ``string`` parameter in the ``.add()`` method that added
the pattern to the set.
``.string()`` fails, returning NULL with an a ``VCL_Error`` message in
the log, if:
* ``n`` is greater than the number of patterns in the set.
* The values of ``n`` and ``select`` are invalid:
* ``n`` is greater than the number of patterns in the set.
* ``n`` <= 0 (or left to the default), but ``.match()`` was not called
earlier in the same task scope (client or backend context).
* ``n`` <= 0 (or left to the default), but ``.match()`` was not
called earlier in the same task scope (client or backend context).
* ``n`` <= 0, but the previous ``.match()`` call returned ``false``.
* ``n`` <= 0, but the previous ``.match()`` call returned ``false``.
* ``n`` <= 0 and no value is given for the ``select`` ENUM, but more
than one pattern matched in the previous ``.match()`` call.
* ``n`` <= 0 and no value is given for the ``select`` ENUM, but more
than one pattern matched in the previous ``.match()`` call.
* A pattern from the set is selected as described above, but no string
was associated with that pattern; that is, the ``string`` parameter
was not set in the ``.add()`` call that added the pattern.
* No string was associated with the pattern selected by ``n`` and
``select``; that is, the ``string`` parameter was not set in the
``.add()`` call that added the pattern.
Examples::
......@@ -1037,25 +1068,13 @@ call to ``.match()`` in the same task scope (client or backend
context).
The rules for selecting a pattern from the set and its associated
backend are the same as for ``.string()`` above:
* If ``n`` > 0, then return the string associated with the `nth`
pattern added to the set with the ``backend`` parameter of the
``.add()`` method, counting from 1 (independent of any previous
``.match()`` call).
* If ``n`` <= 0 (or left to the default) and exactly one pattern in
the set matched in the most recent invocation of ``.match()``
(``.nmatches()`` == 1), then return the backend associated with that
pattern (ignoring the value of ``select``).
* If ``n`` <= 0 and ``.nmatches()`` > 1, then return the backend
associated with the first or last matching pattern in the set
as determined by the ``select`` parameter.
backend based on ``n`` and ``select`` are the same as described above
for ``.string()``.
``.backend()`` fails, returning NULL with an a ``VCL_Error`` message
in the log, under the same conditions described for ``.string()``
above.
above -- ``n`` and ``select`` are invalid, or no backend was
associated with the selected pattern with the ``.add()`` method.
Example::
......@@ -1087,6 +1106,72 @@ Example::
}
}
$Method STRING .sub(STRING text, STRING rewrite,
STRING fallback="**SUB METHOD FAILED**",
INT n=0, ENUM {FIRST, LAST} select=0)
Returns the result of the method call ``.sub(text, rewrite, fallback)``,
as documented above for the ``regex`` interface, invoked on the `nth`
pattern added to the set, or on the pattern in the set that matched in
the most recent call to ``.match()`` in the same task scope.
``.sub()`` requires that the pattern it identifies was saved as an
internal ``regex`` object, by setting ``save`` to true when it was
added with the ``.add()`` method.
The associated pattern is determined by ``n`` and ``select`` according
to the rules given above. If an internal ``regex`` object was saved
for that pattern, then the result of the ``.sub()`` method invoked on
that object is returned.
``.sub()`` fails, returning NULL with a ``VCL_Error`` message in the
log, if:
* The values of ``n`` and ``select`` are invalid, according to the
rules given above.
* ``save`` was false in the ``.add()`` method for the pattern
identified by ``n`` and ``select``; that is, no internal ``regex``
object was saved on which the ``.sub()`` method could have been
invoked.
* The ``.sub()`` method invoked on the ``regex`` object fails for any
of the reasons described for ``regex.sub()``.
Examples::
# Generate synthethic redirect responses on URLs that match a set of
# patterns, rewriting the URL according to the matched pattern.
# In this example, we set the new URL in the redirect location to
# the path that comes after the prefix of the original req.url.
sub vcl_init {
new matcher = re2.set(anchor=start);
matcher.add("/foo/(.*)", save=true);
matcher.add("/bar/(.*)", save=true);
matcher.add("/baz/(.*)", save=true);
matcher.compile();
}
sub vcl_recv {
if (matcher.match(req.url)) {
if (matcher.nmatches() != 1) {
return(fail);
}
return(synth(1301));
}
}
sub vcl_synth {
if (resp.status == 1301) {
# matcher.sub() rewrites the URL to the subpath after the
# original prefix.
set resp.http.Location
= "http://www.otherdomain.org" + matcher.sub(req.url, "/\1");
return(deliver);
}
}
$Function STRING version()
Return the version string for this VMOD.
......
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