Skip to content

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

Update doc formatting for changes in the vmodtool since Varnish 5.0.

parent 507f934e
Hide whitespace changes
Inline Side-by-side
Showing with 464 additions and 462 deletions
README.rst
View file @ c8c28b68
......@@ -34,7 +34,7 @@ import re2 [from "path"] ;
STRING <obj>.sub(STRING text, STRING rewrite)
STRING <obj>.suball(STRING text, STRING rewrite)
STRING <obj>.extract(STRING text, STRING rewrite)
# regex function interface
BOOL re2.match(STRING pattern, STRING subject [, <regex options>])
STRING re2.backref(INT ref)
......@@ -113,7 +113,7 @@ an alternation -- a group of patterns combined with ``|`` for "or". For
example::
import re2;
sub vcl_init {
new myset = re2.set();
myset.add("foo");
......@@ -198,38 +198,28 @@ turned off.
CONTENTS
========
* STRING backref(PRIV_TASK, INT, STRING)
* STRING extract(STRING, STRING, STRING, STRING, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
* 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)
* Object regex
* STRING regex.backref(INT, STRING)
* STRING regex.extract(STRING, STRING, STRING)
* BOOL regex.match(STRING)
* STRING regex.namedref(STRING, STRING)
* STRING regex.sub(STRING, STRING, STRING)
* STRING regex.suball(STRING, STRING, STRING)
* Object set
* VOID set.add(STRING)
* VOID set.compile()
* BOOL set.match(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)
* set(ENUM {none,start,both}, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
* STRING version()
.. _obj_regex:
Object regex
============
regex
-----
::
Prototype
new OBJECT = re2.regex(STRING pattern [, <regex options>])
new OBJ = regex(STRING pattern, 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)
Description
Create a regex object from ``pattern`` and the given options (or option
defaults). If the pattern is invalid, then VCL will fail to load and the VCC
compiler will emit an error message.
Create a regex object from ``pattern`` and the given options (or
option defaults). If the pattern is invalid, then VCL will fail to
load and the VCC compiler will emit an error message.
Example::
......@@ -244,15 +234,15 @@ Example::
.. _func_regex.match:
BOOL regex.match(STRING)
------------------------
regex.match
-----------
::
Prototype
BOOL regex.match(STRING)
Description
Returns ``true`` if and only if the compiled regex matches the given
string; corresponds to VCL's infix operator ``~``.
Returns ``true`` if and only if the compiled regex matches the given
string; corresponds to VCL's infix operator ``~``.
Example::
......@@ -262,48 +252,51 @@ Example::
.. _func_regex.backref:
STRING regex.backref(INT, STRING)
---------------------------------
Prototype
STRING regex.backref(INT ref, STRING fallback)
Description
Returns the `nth` captured subexpression from the most recent successful
call of the ``.match()`` method for this object in the same client or backend,
context, or a fallback string in case the capture fails. Backref 0 indicates
the entire matched string. Thus this function behaves like the ``\n`` in the
native VCL functions ``regsub`` and ``regsuball``, and the ``$1``, ``$2`` ...
variables in Perl.
Since Varnish client and backend operations run in different threads,
``.backref()`` can only refer back to a ``.match()`` call in the same
thread. Thus a ``.backref()`` call in any of the ``vcl_backend_*``
subroutines -- the backend context -- refers back to a previous ``.match()``
in any of those same subroutines; and a call in any of the other VCL
subroutines -- the client context -- refers back to a ``.match()`` in the
same client context.
After unsuccessful matches, the ``fallback`` string is returned for any call
to ``.backref()``. The default value of ``fallback`` is ``"**BACKREF METHOD
FAILED**"``. ``.backref()`` always fails after a failed match, even if
``.match()`` had been called successfully before the failure.
``.backref()`` may also return ``fallback`` after a successful match, if
no captured group in the matching string corresponds to the backref number.
For example, when the pattern ``(a|(b))c`` matches the string ``ac``, there
is no backref 2, since nothing matches ``b`` in the string.
The VCL infix operators ``~`` and ``!~`` do not affect this method, nor do
the functions ``regsub`` or ``regsuball``. Nor is it affected by the matches
performed by any other method or function in this VMOD (such as the ``sub()``,
``suball()`` or ``extract()`` methods or functions, or the ``set`` object's
``.match()`` method).
``.backref()`` fails, returning ``fallback`` and writing an error
message to the Varnish log with the ``VCL_Error`` tag, under the
following conditions (even if a previous match was successful and a
substring could have been captured):
regex.backref
-------------
::
STRING regex.backref(INT ref, STRING fallback="**BACKREF METHOD FAILED**")
Returns the `nth` captured subexpression from the most recent
successful call of the ``.match()`` method for this object in the same
client or backend, context, or a fallback string in case the capture
fails. Backref 0 indicates the entire matched string. Thus this
function behaves like the ``\n`` in the native VCL functions
``regsub`` and ``regsuball``, and the ``$1``, ``$2`` ... variables in
Perl.
Since Varnish client and backend operations run in different threads,
``.backref()`` can only refer back to a ``.match()`` call in the same
thread. Thus a ``.backref()`` call in any of the ``vcl_backend_*``
subroutines -- the backend context -- refers back to a previous
``.match()`` in any of those same subroutines; and a call in any of
the other VCL subroutines -- the client context -- refers back to a
``.match()`` in the same client context.
After unsuccessful matches, the ``fallback`` string is returned for
any call to ``.backref()``. The default value of ``fallback`` is
``"**BACKREF METHOD FAILED**"``. ``.backref()`` always fails after a
failed match, even if ``.match()`` had been called successfully before
the failure.
``.backref()`` may also return ``fallback`` after a successful match,
if no captured group in the matching string corresponds to the backref
number. For example, when the pattern ``(a|(b))c`` matches the string
``ac``, there is no backref 2, since nothing matches ``b`` in the
string.
The VCL infix operators ``~`` and ``!~`` do not affect this method,
nor do the functions ``regsub`` or ``regsuball``. Nor is it affected
by the matches performed by any other method or function in this VMOD
(such as the ``sub()``, ``suball()`` or ``extract()`` methods or
functions, or the ``set`` object's ``.match()`` method).
``.backref()`` fails, returning ``fallback`` and writing an error
message to the Varnish log with the ``VCL_Error`` tag, under the
following conditions (even if a previous match was successful and a
substring could have been captured):
* The ``fallback`` string is undefined, for example if set from an unset
header variable.
......@@ -323,34 +316,38 @@ Example::
.. _func_regex.namedref:
STRING regex.namedref(STRING, STRING)
-------------------------------------
regex.namedref
--------------
::
Prototype
STRING regex.namedref(STRING name, STRING fallback)
STRING regex.namedref(STRING name, STRING fallback="**NAMEDREF METHOD FAILED**")
Description
Returns the captured subexpression designated by ``name`` from the most
recent successful call to ``.match()`` in the current context (client or
backend), or ``fallback`` in case of failure.
Returns the captured subexpression designated by ``name`` from the
most recent successful call to ``.match()`` in the current context
(client or backend), or ``fallback`` in case of failure.
Named capturing groups are written in RE2 as: ``(?P<name>re)``. (Note that
this syntax with ``P``, inspired by Python, differs from the notation for
named capturing groups in PCRE.) Thus when ``(?P<foo>.+)bar$`` matches
``bazbar``, then ``.namedref("foo")`` returns ``baz``.
Named capturing groups are written in RE2 as: ``(?P<name>re)``. (Note
that this syntax with ``P``, inspired by Python, differs from the
notation for named capturing groups in PCRE.) Thus when
``(?P<foo>.+)bar$`` matches ``bazbar``, then ``.namedref("foo")``
returns ``baz``.
Note that a named capturing group can also be referenced as a numbered group.
So in the previous example, ``.backref(1)`` also returns ``baz``.
Note that a named capturing group can also be referenced as a numbered
group. So in the previous example, ``.backref(1)`` also returns
``baz``.
``fallback`` is returned when ``.namedref()`` is called after an
unsuccessful match. The default fallback is ``"**NAMEDREF METHOD FAILED**"``.
``fallback`` is returned when ``.namedref()`` is called after an
unsuccessful match. The default fallback is ``"**NAMEDREF METHOD
FAILED**"``.
Like ``.backref()``, ``.namedref()`` is not affected by native VCL regex
operations, nor by any other matches performed by methods or functions of
the VMOD, except for a prior ``.match()`` for the same object.
Like ``.backref()``, ``.namedref()`` is not affected by native VCL
regex operations, nor by any other matches performed by methods or
functions of the VMOD, except for a prior ``.match()`` for the same
object.
``.namedref()`` fails, returning ``fallback`` and logging a ``VCL_Error``
message, if:
``.namedref()`` fails, returning ``fallback`` and logging a
``VCL_Error`` message, if:
* The ``fallback`` string is undefined.
* ``name`` is undefined or the empty string.
......@@ -364,7 +361,7 @@ Example::
sub vcl_init {
new domainmatcher = re2.regex("^www\.(?P<domain>[^.]+)\.com$");
}
sub vcl_recv {
if (domainmatcher.match(req.http.Host)) {
set req.http.X-Domain = domainmatcher.namedref("domain");
......@@ -373,25 +370,25 @@ Example::
.. _func_regex.sub:
STRING regex.sub(STRING, STRING, STRING)
----------------------------------------
regex.sub
---------
Prototype
STRING regex.sub(STRING text, STRING rewrite, STRING fallback)
::
STRING regex.sub(STRING text, STRING rewrite, STRING fallback="**SUB METHOD FAILED**")
Description
If the compiled pattern for this regex object matches ``text``, then
return the result of replacing the first match in ``text`` with ``rewrite``.
Within ``rewrite``, ``\1`` through ``\9`` can be used to insert the
the numbered capturing group from the pattern, and ``\0`` to insert the
entire matching text. This method corresponds to the VCL native function
``regsub()``.
If the compiled pattern for this regex object matches ``text``, then
return the result of replacing the first match in ``text`` with
``rewrite``. Within ``rewrite``, ``\1`` through ``\9`` can be used to
insert the the numbered capturing group from the pattern, and ``\0``
to insert the entire matching text. This method corresponds to the VCL
native function ``regsub()``.
``fallback`` is returned if the pattern does not match ``text``. The default
fallback is ``"**SUB METHOD FAILED**"``.
``fallback`` is returned if the pattern does not match ``text``. The
default fallback is ``"**SUB METHOD FAILED**"``.
``.sub()`` fails, returning ``fallback`` and logging a ``VCL_Error`` message,
if:
``.sub()`` fails, returning ``fallback`` and logging a ``VCL_Error``
message, if:
* Any of ``text``, ``rewrite`` or ``fallback`` are undefined.
* There is insufficient workspace for the rewritten string.
......@@ -410,22 +407,23 @@ Example::
.. _func_regex.suball:
STRING regex.suball(STRING, STRING, STRING)
-------------------------------------------
regex.suball
------------
::
Prototype
STRING regex.suball(STRING text, STRING rewrite, STRING fallback)
STRING regex.suball(STRING text, STRING rewrite, STRING fallback="**SUBALL METHOD FAILED**")
Description
Like ``.sub()``, except that all successive non-overlapping matches in
``text`` are replaced with ``rewrite``. This method corresponds to VCL
native ``regsuball()``.
Like ``.sub()``, except that all successive non-overlapping matches in
``text`` are replaced with ``rewrite``. This method corresponds to VCL
native ``regsuball()``.
The default fallback is ``"**SUBALL METHOD FAILED**"``. ``.suball()``
fails under the same conditions as ``.sub()``.
The default fallback is ``"**SUBALL METHOD FAILED**"``. ``.suball()``
fails under the same conditions as ``.sub()``.
Since only non-overlapping matches are substituted, replacing ``"ana"``
within ``"banana"`` only results in one substitution, not two.
Since only non-overlapping matches are substituted, replacing
``"ana"`` within ``"banana"`` only results in one substitution, not
two.
Example::
......@@ -441,19 +439,19 @@ Example::
.. _func_regex.extract:
STRING regex.extract(STRING, STRING, STRING)
--------------------------------------------
regex.extract
-------------
::
Prototype
STRING regex.extract(STRING text, STRING rewrite, STRING fallback)
STRING regex.extract(STRING text, STRING rewrite, STRING fallback="**EXTRACT METHOD FAILED**")
Description
If the compiled pattern for this regex object matches ``text``, then
return ``rewrite`` with substitutions from the matching portions of
``text``. Non-matching substrings of ``text`` are ignored.
If the compiled pattern for this regex object matches ``text``, then
return ``rewrite`` with substitutions from the matching portions of
``text``. Non-matching substrings of ``text`` are ignored.
The default fallback is ``"**EXTRACT METHOD FAILED**"``. Like ``.sub()``
and ``.suball()``, ``.extract()`` fails if:
The default fallback is ``"**EXTRACT METHOD FAILED**"``. Like
``.sub()`` and ``.suball()``, ``.extract()`` fails if:
* Any of ``text``, ``rewrite`` or ``fallback`` are undefined.
* There is insufficient workspace for the rewritten string.
......@@ -474,19 +472,19 @@ regex functional interface
.. _func_match:
BOOL match(PRIV_TASK, STRING, STRING, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
------------------------------------------------------------------------------------------------------------
match
-----
Prototype
BOOL match(PRIV_TASK, STRING pattern, STRING subject, BOOL utf8, BOOL posix_syntax, BOOL longest_match, INT max_mem, BOOL literal, BOOL never_nl, BOOL dot_nl, BOOL never_capture, BOOL case_sensitive, BOOL perl_classes, BOOL word_boundary, BOOL one_line)
::
Description
Like the ``regex.match()`` method, return ``true`` if ``pattern`` matches
``subject``, where ``pattern`` is compiled with the given options (or default
options) on each invocation.
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)
If ``pattern`` fails to compile, then an error message is logged with
the ``VCL_Error`` tag, and ``false`` is returned.
Like the ``regex.match()`` method, return ``true`` if ``pattern``
matches ``subject``, where ``pattern`` is compiled with the given
options (or default options) on each invocation.
If ``pattern`` fails to compile, then an error message is logged with
the ``VCL_Error`` tag, and ``false`` is returned.
Example::
......@@ -497,26 +495,26 @@ Example::
.. _func_backref:
STRING backref(PRIV_TASK, INT, STRING)
--------------------------------------
backref
-------
::
Prototype
STRING backref(PRIV_TASK, INT ref, STRING fallback)
STRING backref(PRIV_TASK, INT ref, STRING fallback="**BACKREF FUNCTION FAILED**")
Description
Returns the `nth` captured subexpression from the most recent successful
call of the ``match()`` function in the current client or backend context,
or a fallback string if the capture fails. The default ``fallback`` is
``"**BACKREF FUNCTION FAILED**"``.
Returns the `nth` captured subexpression from the most recent
successful call of the ``match()`` function in the current client or
backend context, or a fallback string if the capture fails. The
default ``fallback`` is ``"**BACKREF FUNCTION FAILED**"``.
Similarly to the ``regex.backref()`` method, ``fallback`` is returned
after any failed invocation of the ``match()`` function, or if there
is no captured group corresponding to the backref number. The function
is not affected by native VCL regex operations, or any other method or
function of the VMOD except for the ``match()`` function.
Similarly to the ``regex.backref()`` method, ``fallback`` is returned
after any failed invocation of the ``match()`` function, or if there
is no captured group corresponding to the backref number. The function
is not affected by native VCL regex operations, or any other method or
function of the VMOD except for the ``match()`` function.
The function fails, returning ``fallback`` and logging a ``VCL_Error``
message, under the same conditions as the corresponding method:
The function fails, returning ``fallback`` and logging a ``VCL_Error``
message, under the same conditions as the corresponding method:
* ``fallback`` is undefined.
* ``never_capture`` was true in the previous invocation of the ``match()``
......@@ -536,23 +534,23 @@ Example::
.. _func_namedref:
STRING namedref(PRIV_TASK, STRING, STRING)
------------------------------------------
namedref
--------
Prototype
STRING namedref(PRIV_TASK, STRING name, STRING fallback)
::
STRING namedref(PRIV_TASK, STRING name, STRING fallback="**NAMEDREF FUNCTION FAILED**")
Description
Returns the captured subexpression designated by ``name`` from the most
recent successful call to the ``match()`` function in the current context, or
``fallback`` in case of failure. The default fallback is ``"**NAMEDREF
FUNCTION FAILED**"``.
Returns the captured subexpression designated by ``name`` from the
most recent successful call to the ``match()`` function in the current
context, or ``fallback`` in case of failure. The default fallback is
``"**NAMEDREF FUNCTION FAILED**"``.
The function returns ``fallback`` when the previous invocation of the
``match()`` function failed, and is only affected by use of the ``match()``
function. The function fails, returning ``fallback`` and logging a
``VCL_Error`` message, under the same conditions as the corresponding
method:
The function returns ``fallback`` when the previous invocation of the
``match()`` function failed, and is only affected by use of the
``match()`` function. The function fails, returning ``fallback`` and
logging a ``VCL_Error`` message, under the same conditions as the
corresponding method:
* ``fallback`` is undefined.
* ``name`` is undefined or the empty string.
......@@ -570,24 +568,24 @@ Example::
.. _func_sub:
STRING sub(STRING, STRING, STRING, STRING, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
-----------------------------------------------------------------------------------------------------------------
sub
---
::
Prototype
STRING sub(STRING pattern, STRING text, STRING rewrite, STRING fallback, BOOL utf8, BOOL posix_syntax, BOOL longest_match, INT max_mem, BOOL literal, BOOL never_nl, BOOL dot_nl, BOOL never_capture, BOOL case_sensitive, BOOL perl_classes, BOOL word_boundary, BOOL one_line)
STRING sub(STRING pattern, STRING text, STRING rewrite, STRING fallback="**SUB FUNCTION FAILED**", 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)
Description
Compiles ``pattern`` with the given options, and if it matches ``text``,
then return the result of replacing the first match in ``text`` with
``rewrite``. As with the ``regex.sub()`` method, ``\0`` through ``\9``
may be used in ``rewrite`` to substitute captured groups from the
pattern.
Compiles ``pattern`` with the given options, and if it matches
``text``, then return the result of replacing the first match in
``text`` with ``rewrite``. As with the ``regex.sub()`` method, ``\0``
through ``\9`` may be used in ``rewrite`` to substitute captured
groups from the pattern.
``fallback`` is returned if the pattern does not match ``text``. The default
fallback is ``"**SUB FUNCTION FAILED**"``.
``fallback`` is returned if the pattern does not match ``text``. The
default fallback is ``"**SUB FUNCTION FAILED**"``.
``sub()`` fails, returning ``fallback`` and logging a ``VCL_Error`` message,
if:
``sub()`` fails, returning ``fallback`` and logging a ``VCL_Error``
message, if:
* ``pattern`` cannot be compiled.
* Any of ``text``, ``rewrite`` or ``fallback`` are undefined.
......@@ -603,18 +601,18 @@ Example::
.. _func_suball:
STRING suball(STRING, STRING, STRING, STRING, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
--------------------------------------------------------------------------------------------------------------------
suball
------
Prototype
STRING suball(STRING pattern, STRING text, STRING rewrite, STRING fallback, BOOL utf8, BOOL posix_syntax, BOOL longest_match, INT max_mem, BOOL literal, BOOL never_nl, BOOL dot_nl, BOOL never_capture, BOOL case_sensitive, BOOL perl_classes, BOOL word_boundary, BOOL one_line)
::
STRING suball(STRING pattern, STRING text, STRING rewrite, STRING fallback="**SUBALL FUNCTION FAILED**", 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)
Description
Like the ``sub()`` function, except that all successive non-overlapping
matches in ``text`` are replace with ``rewrite``.
Like the ``sub()`` function, except that all successive
non-overlapping matches in ``text`` are replace with ``rewrite``.
The default fallback is ``"**SUBALL FUNCTION FAILED**"``. The ``suball()``
function fails under the same conditions as ``sub()``.
The default fallback is ``"**SUBALL FUNCTION FAILED**"``. The
``suball()`` function fails under the same conditions as ``sub()``.
Example::
......@@ -626,19 +624,20 @@ Example::
.. _func_extract:
STRING extract(STRING, STRING, STRING, STRING, BOOL, BOOL, BOOL, INT, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL, BOOL)
---------------------------------------------------------------------------------------------------------------------
extract
-------
::
Prototype
STRING extract(STRING pattern, STRING text, STRING rewrite, STRING fallback, BOOL utf8, BOOL posix_syntax, BOOL longest_match, INT max_mem, BOOL literal, BOOL never_nl, BOOL dot_nl, BOOL never_capture, BOOL case_sensitive, BOOL perl_classes, BOOL word_boundary, BOOL one_line)
STRING extract(STRING pattern, STRING text, STRING rewrite, STRING fallback="**EXTRACT FUNCTION FAILED**", 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)
Description
Compiles ``pattern`` with the given options, and if it matches ``text``,
then return ``rewrite`` with substitutions from the matching portions of
``text``, ignoring the non-matching portions.
Compiles ``pattern`` with the given options, and if it matches
``text``, then return ``rewrite`` with substitutions from the matching
portions of ``text``, ignoring the non-matching portions.
The default fallback is ``"**EXTRACT FUNCTION FAILED**"``. The ``extract()``
function fails under the same conditions as ``sub()`` and ``suball()``.
The default fallback is ``"**EXTRACT FUNCTION FAILED**"``. The
``extract()`` function fails under the same conditions as ``sub()``
and ``suball()``.
Example::
......@@ -649,34 +648,35 @@ Example::
.. _obj_set:
Object set
==========
set
---
::
Prototype
new OBJECT = re2.set([ENUM anchor] [, <regex options>])
Description
Initialize a set object that represents several patterns combined by
alternation -- ``|`` for "or".
Optional parameters control the interpretation of the resulting composed
pattern. The ``anchor`` parameter is an enum that can have the values
``none``, ``start`` or ``both``, where ``none`` is the default. ``start``
means that each pattern is matched as if it begins with ``^`` for
start-of-text, and ``both`` means that each pattern is anchored with both
``^`` at the beginning and ``$`` for end-of-text at the end. ``none`` means
that each pattern is interpreted as a partial match (although individual
patterns within the set may have either of ``^`` of ``$``).
For example, if a set is initialized with ``anchor=both``, and the patterns
``foo`` and ``bar`` are added, then matches against the set match a string
against ``^foo$|^bar$``, or equivalently ``^(foo|bar)$``.
The usual regex options can be set, which then control matching against
the resulting composed pattern. However, the ``never_capture`` option
cannot be set, and is always implicitly true, since backrefs and
namedrefs are not possible with sets.
new OBJ = set(ENUM {none,start,both} anchor="none", 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 case_sensitive=1, BOOL perl_classes=0, BOOL word_boundary=0, BOOL one_line=0)
Initialize a set object that represents several patterns combined by
alternation -- ``|`` for "or".
Optional parameters control the interpretation of the resulting
composed pattern. The ``anchor`` parameter is an enum that can have
the values ``none``, ``start`` or ``both``, where ``none`` is the
default. ``start`` means that each pattern is matched as if it begins
with ``^`` for start-of-text, and ``both`` means that each pattern is
anchored with both ``^`` at the beginning and ``$`` for end-of-text at
the end. ``none`` means that each pattern is interpreted as a partial
match (although individual patterns within the set may have either of
``^`` of ``$``).
For example, if a set is initialized with ``anchor=both``, and the
patterns ``foo`` and ``bar`` are added, then matches against the set
match a string against ``^foo$|^bar$``, or equivalently
``^(foo|bar)$``.
The usual regex options can be set, which then control matching
against the resulting composed pattern. However, the ``never_capture``
option cannot be set, and is always implicitly true, since backrefs
and namedrefs are not possible with sets.
Example::
......@@ -697,25 +697,25 @@ Example::
.. _func_set.add:
VOID set.add(STRING)
--------------------
set.add
-------
::
Prototype
VOID set.add(STRING)
Description
Add the given pattern to the set. If the pattern is invalid, ``.add()``
fails, and the VCL will fail to load, with an error message describing
the problem.
Add the given pattern to the set. If the pattern is invalid,
``.add()`` fails, and the VCL will fail to load, with an error message
describing the problem.
``.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 effect.
If it is called in ``vcl_init`` after ``.compile()``, then the VCL load
will fail with an error message.
``.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
effect. If it is called in ``vcl_init`` after ``.compile()``, then the
VCL load will fail with an error message.
In other words, add all patterns to the set in ``vcl_init``, and finally
call ``.compile()`` when you're done.
In other words, add all patterns to the set in ``vcl_init``, and
finally call ``.compile()`` when you're done.
Example::
......@@ -732,43 +732,44 @@ Example::
.. _func_set.compile:
VOID set.compile()
------------------
set.compile
-----------
::
Prototype
VOID set.compile()
Description
Compile the compound pattern represented by the set -- an alternation of
all patterns added by ``.add()``.
Compile the compound pattern represented by the set -- an alternation
of all patterns added by ``.add()``.
``.compile()`` may fail if the ``max_mem`` setting is not large enough
for the composed pattern. In that case, the VCL load will fail with an
error message (then consider a larger value for ``max_mem`` in the set
constructor).
``.compile()`` may fail if the ``max_mem`` setting is not large enough
for the composed pattern. In that case, the VCL load will fail with an
error message (then consider a larger value for ``max_mem`` in the set
constructor).
``.compile()`` MUST be called in ``vcl_init``, and MAY NOT be called
more than once for a set object. If it is called in any other subroutine,
a ``VCL_Error`` message is logged, and the call has no effect. If it
is called a second time in ``vcl_init``, the VCL load will fail.
``.compile()`` MUST be called in ``vcl_init``, and MAY NOT be called
more than once for a set object. If it is called in any other
subroutine, a ``VCL_Error`` message is logged, and the call has no
effect. If it is called a second time in ``vcl_init``, the VCL load
will fail.
See above for examples.
See above for examples.
.. _func_set.match:
BOOL set.match(STRING)
----------------------
set.match
---------
::
Prototype
BOOL set.match(STRING)
Description
Returns ``true`` if the given string matches the compound pattern
represented by the set, i.e. if it matches any of the patterns that
were added to the set.
Returns ``true`` if the given string matches the compound pattern
represented by the set, i.e. if it matches any of the patterns that
were added to the set.
``.match()`` MUST be called after ``.compile()``; otherwise the
match always fails.
``.match()`` MUST be called after ``.compile()``; otherwise the match
always fails.
Example::
......@@ -778,14 +779,14 @@ Example::
.. _func_version:
STRING version()
----------------
version
-------
::
Prototype
STRING version()
Description
Return the version string for this VMOD.
Return the version string for this VMOD.
Example::
......@@ -912,3 +913,16 @@ project. See LICENSE for details.
* Copyright (c) 2016 UPLEX Nils Goroll Systemoptimierung
COPYRIGHT
=========
::
Copyright (c) 2016 UPLEX Nils Goroll Systemoptimierung
All rights reserved
Author: Geoffrey Simmons <geoffrey.simmons@uplex.de>
See LICENSE
src/vmod_re2.vcc
View file @ c8c28b68
......@@ -186,13 +186,9 @@ $Object regex(STRING pattern, BOOL utf8=0, BOOL posix_syntax=0,
BOOL case_sensitive=1, BOOL perl_classes=0,
BOOL word_boundary=0, BOOL one_line=0)
Prototype
new OBJECT = re2.regex(STRING pattern [, <regex options>])
Description
Create a regex object from ``pattern`` and the given options (or option
defaults). If the pattern is invalid, then VCL will fail to load and the VCC
compiler will emit an error message.
Create a regex object from ``pattern`` and the given options (or
option defaults). If the pattern is invalid, then VCL will fail to
load and the VCC compiler will emit an error message.
Example::
......@@ -207,9 +203,8 @@ Example::
$Method BOOL .match(STRING)
Description
Returns ``true`` if and only if the compiled regex matches the given
string; corresponds to VCL's infix operator ``~``.
Returns ``true`` if and only if the compiled regex matches the given
string; corresponds to VCL's infix operator ``~``.
Example::
......@@ -219,42 +214,44 @@ Example::
$Method STRING .backref(INT ref, STRING fallback = "**BACKREF METHOD FAILED**")
Description
Returns the `nth` captured subexpression from the most recent successful
call of the ``.match()`` method for this object in the same client or backend,
context, or a fallback string in case the capture fails. Backref 0 indicates
the entire matched string. Thus this function behaves like the ``\n`` in the
native VCL functions ``regsub`` and ``regsuball``, and the ``$1``, ``$2`` ...
variables in Perl.
Since Varnish client and backend operations run in different threads,
``.backref()`` can only refer back to a ``.match()`` call in the same
thread. Thus a ``.backref()`` call in any of the ``vcl_backend_*``
subroutines -- the backend context -- refers back to a previous ``.match()``
in any of those same subroutines; and a call in any of the other VCL
subroutines -- the client context -- refers back to a ``.match()`` in the
same client context.
After unsuccessful matches, the ``fallback`` string is returned for any call
to ``.backref()``. The default value of ``fallback`` is ``"**BACKREF METHOD
FAILED**"``. ``.backref()`` always fails after a failed match, even if
``.match()`` had been called successfully before the failure.
``.backref()`` may also return ``fallback`` after a successful match, if
no captured group in the matching string corresponds to the backref number.
For example, when the pattern ``(a|(b))c`` matches the string ``ac``, there
is no backref 2, since nothing matches ``b`` in the string.
The VCL infix operators ``~`` and ``!~`` do not affect this method, nor do
the functions ``regsub`` or ``regsuball``. Nor is it affected by the matches
performed by any other method or function in this VMOD (such as the ``sub()``,
``suball()`` or ``extract()`` methods or functions, or the ``set`` object's
``.match()`` method).
``.backref()`` fails, returning ``fallback`` and writing an error
message to the Varnish log with the ``VCL_Error`` tag, under the
following conditions (even if a previous match was successful and a
substring could have been captured):
Returns the `nth` captured subexpression from the most recent
successful call of the ``.match()`` method for this object in the same
client or backend, context, or a fallback string in case the capture
fails. Backref 0 indicates the entire matched string. Thus this
function behaves like the ``\n`` in the native VCL functions
``regsub`` and ``regsuball``, and the ``$1``, ``$2`` ... variables in
Perl.
Since Varnish client and backend operations run in different threads,
``.backref()`` can only refer back to a ``.match()`` call in the same
thread. Thus a ``.backref()`` call in any of the ``vcl_backend_*``
subroutines -- the backend context -- refers back to a previous
``.match()`` in any of those same subroutines; and a call in any of
the other VCL subroutines -- the client context -- refers back to a
``.match()`` in the same client context.
After unsuccessful matches, the ``fallback`` string is returned for
any call to ``.backref()``. The default value of ``fallback`` is
``"**BACKREF METHOD FAILED**"``. ``.backref()`` always fails after a
failed match, even if ``.match()`` had been called successfully before
the failure.
``.backref()`` may also return ``fallback`` after a successful match,
if no captured group in the matching string corresponds to the backref
number. For example, when the pattern ``(a|(b))c`` matches the string
``ac``, there is no backref 2, since nothing matches ``b`` in the
string.
The VCL infix operators ``~`` and ``!~`` do not affect this method,
nor do the functions ``regsub`` or ``regsuball``. Nor is it affected
by the matches performed by any other method or function in this VMOD
(such as the ``sub()``, ``suball()`` or ``extract()`` methods or
functions, or the ``set`` object's ``.match()`` method).
``.backref()`` fails, returning ``fallback`` and writing an error
message to the Varnish log with the ``VCL_Error`` tag, under the
following conditions (even if a previous match was successful and a
substring could have been captured):
* The ``fallback`` string is undefined, for example if set from an unset
header variable.
......@@ -275,28 +272,31 @@ Example::
$Method STRING .namedref(STRING name,
STRING fallback = "**NAMEDREF METHOD FAILED**")
Description
Returns the captured subexpression designated by ``name`` from the most
recent successful call to ``.match()`` in the current context (client or
backend), or ``fallback`` in case of failure.
Returns the captured subexpression designated by ``name`` from the
most recent successful call to ``.match()`` in the current context
(client or backend), or ``fallback`` in case of failure.
Named capturing groups are written in RE2 as: ``(?P<name>re)``. (Note that
this syntax with ``P``, inspired by Python, differs from the notation for
named capturing groups in PCRE.) Thus when ``(?P<foo>.+)bar$`` matches
``bazbar``, then ``.namedref("foo")`` returns ``baz``.
Named capturing groups are written in RE2 as: ``(?P<name>re)``. (Note
that this syntax with ``P``, inspired by Python, differs from the
notation for named capturing groups in PCRE.) Thus when
``(?P<foo>.+)bar$`` matches ``bazbar``, then ``.namedref("foo")``
returns ``baz``.
Note that a named capturing group can also be referenced as a numbered group.
So in the previous example, ``.backref(1)`` also returns ``baz``.
Note that a named capturing group can also be referenced as a numbered
group. So in the previous example, ``.backref(1)`` also returns
``baz``.
``fallback`` is returned when ``.namedref()`` is called after an
unsuccessful match. The default fallback is ``"**NAMEDREF METHOD FAILED**"``.
``fallback`` is returned when ``.namedref()`` is called after an
unsuccessful match. The default fallback is ``"**NAMEDREF METHOD
FAILED**"``.
Like ``.backref()``, ``.namedref()`` is not affected by native VCL regex
operations, nor by any other matches performed by methods or functions of
the VMOD, except for a prior ``.match()`` for the same object.
Like ``.backref()``, ``.namedref()`` is not affected by native VCL
regex operations, nor by any other matches performed by methods or
functions of the VMOD, except for a prior ``.match()`` for the same
object.
``.namedref()`` fails, returning ``fallback`` and logging a ``VCL_Error``
message, if:
``.namedref()`` fails, returning ``fallback`` and logging a
``VCL_Error`` message, if:
* The ``fallback`` string is undefined.
* ``name`` is undefined or the empty string.
......@@ -320,19 +320,18 @@ Example::
$Method STRING .sub(STRING text, STRING rewrite,
STRING fallback = "**SUB METHOD FAILED**")
Description
If the compiled pattern for this regex object matches ``text``, then
return the result of replacing the first match in ``text`` with ``rewrite``.
Within ``rewrite``, ``\1`` through ``\9`` can be used to insert the
the numbered capturing group from the pattern, and ``\0`` to insert the
entire matching text. This method corresponds to the VCL native function
``regsub()``.
If the compiled pattern for this regex object matches ``text``, then
return the result of replacing the first match in ``text`` with
``rewrite``. Within ``rewrite``, ``\1`` through ``\9`` can be used to
insert the the numbered capturing group from the pattern, and ``\0``
to insert the entire matching text. This method corresponds to the VCL
native function ``regsub()``.
``fallback`` is returned if the pattern does not match ``text``. The default
fallback is ``"**SUB METHOD FAILED**"``.
``fallback`` is returned if the pattern does not match ``text``. The
default fallback is ``"**SUB METHOD FAILED**"``.
``.sub()`` fails, returning ``fallback`` and logging a ``VCL_Error`` message,
if:
``.sub()`` fails, returning ``fallback`` and logging a ``VCL_Error``
message, if:
* Any of ``text``, ``rewrite`` or ``fallback`` are undefined.
* There is insufficient workspace for the rewritten string.
......@@ -352,16 +351,16 @@ Example::
$Method STRING .suball(STRING text, STRING rewrite,
STRING fallback = "**SUBALL METHOD FAILED**")
Description
Like ``.sub()``, except that all successive non-overlapping matches in
``text`` are replaced with ``rewrite``. This method corresponds to VCL
native ``regsuball()``.
Like ``.sub()``, except that all successive non-overlapping matches in
``text`` are replaced with ``rewrite``. This method corresponds to VCL
native ``regsuball()``.
The default fallback is ``"**SUBALL METHOD FAILED**"``. ``.suball()``
fails under the same conditions as ``.sub()``.
The default fallback is ``"**SUBALL METHOD FAILED**"``. ``.suball()``
fails under the same conditions as ``.sub()``.
Since only non-overlapping matches are substituted, replacing ``"ana"``
within ``"banana"`` only results in one substitution, not two.
Since only non-overlapping matches are substituted, replacing
``"ana"`` within ``"banana"`` only results in one substitution, not
two.
Example::
......@@ -378,13 +377,12 @@ Example::
$Method STRING .extract(STRING text, STRING rewrite,
STRING fallback = "**EXTRACT METHOD FAILED**")
Description
If the compiled pattern for this regex object matches ``text``, then
return ``rewrite`` with substitutions from the matching portions of
``text``. Non-matching substrings of ``text`` are ignored.
If the compiled pattern for this regex object matches ``text``, then
return ``rewrite`` with substitutions from the matching portions of
``text``. Non-matching substrings of ``text`` are ignored.
The default fallback is ``"**EXTRACT METHOD FAILED**"``. Like ``.sub()``
and ``.suball()``, ``.extract()`` fails if:
The default fallback is ``"**EXTRACT METHOD FAILED**"``. Like
``.sub()`` and ``.suball()``, ``.extract()`` fails if:
* Any of ``text``, ``rewrite`` or ``fallback`` are undefined.
* There is insufficient workspace for the rewritten string.
......@@ -410,13 +408,12 @@ $Function BOOL match(PRIV_TASK, STRING pattern, STRING subject, BOOL utf8=0,
BOOL case_sensitive=1, BOOL perl_classes=0,
BOOL word_boundary=0, BOOL one_line=0)
Description
Like the ``regex.match()`` method, return ``true`` if ``pattern`` matches
``subject``, where ``pattern`` is compiled with the given options (or default
options) on each invocation.
Like the ``regex.match()`` method, return ``true`` if ``pattern``
matches ``subject``, where ``pattern`` is compiled with the given
options (or default options) on each invocation.
If ``pattern`` fails to compile, then an error message is logged with
the ``VCL_Error`` tag, and ``false`` is returned.
If ``pattern`` fails to compile, then an error message is logged with
the ``VCL_Error`` tag, and ``false`` is returned.
Example::
......@@ -428,20 +425,19 @@ Example::
$Function STRING backref(PRIV_TASK, INT ref,
STRING fallback = "**BACKREF FUNCTION FAILED**")
Description
Returns the `nth` captured subexpression from the most recent successful
call of the ``match()`` function in the current client or backend context,
or a fallback string if the capture fails. The default ``fallback`` is
``"**BACKREF FUNCTION FAILED**"``.
Returns the `nth` captured subexpression from the most recent
successful call of the ``match()`` function in the current client or
backend context, or a fallback string if the capture fails. The
default ``fallback`` is ``"**BACKREF FUNCTION FAILED**"``.
Similarly to the ``regex.backref()`` method, ``fallback`` is returned
after any failed invocation of the ``match()`` function, or if there
is no captured group corresponding to the backref number. The function
is not affected by native VCL regex operations, or any other method or
function of the VMOD except for the ``match()`` function.
Similarly to the ``regex.backref()`` method, ``fallback`` is returned
after any failed invocation of the ``match()`` function, or if there
is no captured group corresponding to the backref number. The function
is not affected by native VCL regex operations, or any other method or
function of the VMOD except for the ``match()`` function.
The function fails, returning ``fallback`` and logging a ``VCL_Error``
message, under the same conditions as the corresponding method:
The function fails, returning ``fallback`` and logging a ``VCL_Error``
message, under the same conditions as the corresponding method:
* ``fallback`` is undefined.
* ``never_capture`` was true in the previous invocation of the ``match()``
......@@ -462,17 +458,16 @@ Example::
$Function STRING namedref(PRIV_TASK, STRING name,
STRING fallback = "**NAMEDREF FUNCTION FAILED**")
Description
Returns the captured subexpression designated by ``name`` from the most
recent successful call to the ``match()`` function in the current context, or
``fallback`` in case of failure. The default fallback is ``"**NAMEDREF
FUNCTION FAILED**"``.
Returns the captured subexpression designated by ``name`` from the
most recent successful call to the ``match()`` function in the current
context, or ``fallback`` in case of failure. The default fallback is
``"**NAMEDREF FUNCTION FAILED**"``.
The function returns ``fallback`` when the previous invocation of the
``match()`` function failed, and is only affected by use of the ``match()``
function. The function fails, returning ``fallback`` and logging a
``VCL_Error`` message, under the same conditions as the corresponding
method:
The function returns ``fallback`` when the previous invocation of the
``match()`` function failed, and is only affected by use of the
``match()`` function. The function fails, returning ``fallback`` and
logging a ``VCL_Error`` message, under the same conditions as the
corresponding method:
* ``fallback`` is undefined.
* ``name`` is undefined or the empty string.
......@@ -495,18 +490,17 @@ $Function STRING sub(STRING pattern, STRING text, STRING rewrite,
BOOL dot_nl=0, BOOL never_capture=0, BOOL case_sensitive=1,
BOOL perl_classes=0, BOOL word_boundary=0, BOOL one_line=0)
Description
Compiles ``pattern`` with the given options, and if it matches ``text``,
then return the result of replacing the first match in ``text`` with
``rewrite``. As with the ``regex.sub()`` method, ``\0`` through ``\9``
may be used in ``rewrite`` to substitute captured groups from the
pattern.
Compiles ``pattern`` with the given options, and if it matches
``text``, then return the result of replacing the first match in
``text`` with ``rewrite``. As with the ``regex.sub()`` method, ``\0``
through ``\9`` may be used in ``rewrite`` to substitute captured
groups from the pattern.
``fallback`` is returned if the pattern does not match ``text``. The default
fallback is ``"**SUB FUNCTION FAILED**"``.
``fallback`` is returned if the pattern does not match ``text``. The
default fallback is ``"**SUB FUNCTION FAILED**"``.
``sub()`` fails, returning ``fallback`` and logging a ``VCL_Error`` message,
if:
``sub()`` fails, returning ``fallback`` and logging a ``VCL_Error``
message, if:
* ``pattern`` cannot be compiled.
* Any of ``text``, ``rewrite`` or ``fallback`` are undefined.
......@@ -528,12 +522,11 @@ $Function STRING suball(STRING pattern, STRING text, STRING rewrite,
BOOL case_sensitive=1, BOOL perl_classes=0,
BOOL word_boundary=0, BOOL one_line=0)
Description
Like the ``sub()`` function, except that all successive non-overlapping
matches in ``text`` are replace with ``rewrite``.
Like the ``sub()`` function, except that all successive
non-overlapping matches in ``text`` are replace with ``rewrite``.
The default fallback is ``"**SUBALL FUNCTION FAILED**"``. The ``suball()``
function fails under the same conditions as ``sub()``.
The default fallback is ``"**SUBALL FUNCTION FAILED**"``. The
``suball()`` function fails under the same conditions as ``sub()``.
Example::
......@@ -551,13 +544,13 @@ $Function STRING extract(STRING pattern, STRING text, STRING rewrite,
BOOL case_sensitive=1, BOOL perl_classes=0,
BOOL word_boundary=0, BOOL one_line=0)
Description
Compiles ``pattern`` with the given options, and if it matches ``text``,
then return ``rewrite`` with substitutions from the matching portions of
``text``, ignoring the non-matching portions.
Compiles ``pattern`` with the given options, and if it matches
``text``, then return ``rewrite`` with substitutions from the matching
portions of ``text``, ignoring the non-matching portions.
The default fallback is ``"**EXTRACT FUNCTION FAILED**"``. The ``extract()``
function fails under the same conditions as ``sub()`` and ``suball()``.
The default fallback is ``"**EXTRACT FUNCTION FAILED**"``. The
``extract()`` function fails under the same conditions as ``sub()``
and ``suball()``.
Example::
......@@ -572,30 +565,28 @@ $Object set(ENUM { none, start, both } anchor="none", BOOL utf8=0,
BOOL case_sensitive=1, BOOL perl_classes=0, BOOL word_boundary=0,
BOOL one_line=0)
Prototype
new OBJECT = re2.set([ENUM anchor] [, <regex options>])
Description
Initialize a set object that represents several patterns combined by
alternation -- ``|`` for "or".
Initialize a set object that represents several patterns combined by
alternation -- ``|`` for "or".
Optional parameters control the interpretation of the resulting composed
pattern. The ``anchor`` parameter is an enum that can have the values
``none``, ``start`` or ``both``, where ``none`` is the default. ``start``
means that each pattern is matched as if it begins with ``^`` for
start-of-text, and ``both`` means that each pattern is anchored with both
``^`` at the beginning and ``$`` for end-of-text at the end. ``none`` means
that each pattern is interpreted as a partial match (although individual
patterns within the set may have either of ``^`` of ``$``).
For example, if a set is initialized with ``anchor=both``, and the patterns
``foo`` and ``bar`` are added, then matches against the set match a string
against ``^foo$|^bar$``, or equivalently ``^(foo|bar)$``.
Optional parameters control the interpretation of the resulting
composed pattern. The ``anchor`` parameter is an enum that can have
the values ``none``, ``start`` or ``both``, where ``none`` is the
default. ``start`` means that each pattern is matched as if it begins
with ``^`` for start-of-text, and ``both`` means that each pattern is
anchored with both ``^`` at the beginning and ``$`` for end-of-text at
the end. ``none`` means that each pattern is interpreted as a partial
match (although individual patterns within the set may have either of
``^`` of ``$``).
For example, if a set is initialized with ``anchor=both``, and the
patterns ``foo`` and ``bar`` are added, then matches against the set
match a string against ``^foo$|^bar$``, or equivalently
``^(foo|bar)$``.
The usual regex options can be set, which then control matching against
the resulting composed pattern. However, the ``never_capture`` option
cannot be set, and is always implicitly true, since backrefs and
namedrefs are not possible with sets.
The usual regex options can be set, which then control matching
against the resulting composed pattern. However, the ``never_capture``
option cannot be set, and is always implicitly true, since backrefs
and namedrefs are not possible with sets.
Example::
......@@ -616,19 +607,18 @@ Example::
$Method VOID .add(STRING)
Description
Add the given pattern to the set. If the pattern is invalid, ``.add()``
fails, and the VCL will fail to load, with an error message describing
the problem.
Add the given pattern to the set. If the pattern is invalid,
``.add()`` fails, and the VCL will fail to load, with an error message
describing the problem.
``.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 effect.
If it is called in ``vcl_init`` after ``.compile()``, then the VCL load
will fail with an error message.
``.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
effect. If it is called in ``vcl_init`` after ``.compile()``, then the
VCL load will fail with an error message.
In other words, add all patterns to the set in ``vcl_init``, and finally
call ``.compile()`` when you're done.
In other words, add all patterns to the set in ``vcl_init``, and
finally call ``.compile()`` when you're done.
Example::
......@@ -645,31 +635,30 @@ Example::
$Method VOID .compile()
Description
Compile the compound pattern represented by the set -- an alternation of
all patterns added by ``.add()``.
Compile the compound pattern represented by the set -- an alternation
of all patterns added by ``.add()``.
``.compile()`` may fail if the ``max_mem`` setting is not large enough
for the composed pattern. In that case, the VCL load will fail with an
error message (then consider a larger value for ``max_mem`` in the set
constructor).
``.compile()`` may fail if the ``max_mem`` setting is not large enough
for the composed pattern. In that case, the VCL load will fail with an
error message (then consider a larger value for ``max_mem`` in the set
constructor).
``.compile()`` MUST be called in ``vcl_init``, and MAY NOT be called
more than once for a set object. If it is called in any other subroutine,
a ``VCL_Error`` message is logged, and the call has no effect. If it
is called a second time in ``vcl_init``, the VCL load will fail.
``.compile()`` MUST be called in ``vcl_init``, and MAY NOT be called
more than once for a set object. If it is called in any other
subroutine, a ``VCL_Error`` message is logged, and the call has no
effect. If it is called a second time in ``vcl_init``, the VCL load
will fail.
See above for examples.
See above for examples.
$Method BOOL .match(STRING)
Description
Returns ``true`` if the given string matches the compound pattern
represented by the set, i.e. if it matches any of the patterns that
were added to the set.
Returns ``true`` if the given string matches the compound pattern
represented by the set, i.e. if it matches any of the patterns that
were added to the set.
``.match()`` MUST be called after ``.compile()``; otherwise the
match always fails.
``.match()`` MUST be called after ``.compile()``; otherwise the match
always fails.
Example::
......@@ -679,8 +668,7 @@ Example::
$Function STRING version()
Description
Return the version string for this VMOD.
Return the version string for this VMOD.
Example::
......
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