Commit dfc71a11 authored by Geoff Simmons's avatar Geoff Simmons

updated README to include match_dyn, and some more details

parent 33f47f4c
...@@ -8,7 +8,7 @@ Varnish Module for Regular Expression Matching with Backref Capture ...@@ -8,7 +8,7 @@ Varnish Module for Regular Expression Matching with Backref Capture
:Manual section: 3 :Manual section: 3
:Author: Geoffrey Simmons :Author: Geoffrey Simmons
:Date: 2013-09-09 :Date: 2013-09-13
:Version: 0.1 :Version: 0.1
SYNOPSIS SYNOPSIS
...@@ -19,6 +19,7 @@ SYNOPSIS ...@@ -19,6 +19,7 @@ SYNOPSIS
import re; import re;
re.match(<string>, <regular expresssion>) re.match(<string>, <regular expresssion>)
re.match_dyn(<string>, <regular expresssion>)
re.backref(<integer>, <fallback>) re.backref(<integer>, <fallback>)
re.version() re.version()
...@@ -41,6 +42,11 @@ Example VCL:: ...@@ -41,6 +42,11 @@ Example VCL::
} }
} }
sub vcl_fetch {
if (re.match_dyn(req.http.Cookie, beresp.http.X-Regex)) {
set resp.http.Foo = re.backref(1, "");
}
}
match match
----- -----
...@@ -50,13 +56,35 @@ Prototype ...@@ -50,13 +56,35 @@ Prototype
Returns Returns
boolean boolean
Description Description
Determines whether a string matches the given regular expression; Determines whether a string matches the given regular
functionally equivalent to VCL's infix operator `~`. It is subject expression, which never changes for the lifetime of the VCL;
to the same limitations, for example as set by the runtime functionally equivalent to VCL's infix operator ``~`` for
paramters `pcre_match_limit` and `pcre_match_limit_recursion`. fixed regex patterns.
``re.match`` only matches against the pattern provided the
first time it's called, and does not detect whether the
pattern is changed after that.
Example Example
``re.match(beresp.http.Surrogate-Control, "max-age=(\d+);mysite")`` ``re.match(beresp.http.Surrogate-Control, "max-age=(\d+);mysite")``
match_dyn
---------
Prototype
re.match_dyn(<string>, <regular expression>)
Returns
boolean
Description
Determines whether a string matches the given regular
expression, which may change during the lifetime of the VCL;
equivalent to VCL's infix operator ``~`` for arbitrary regex
patterns.
``re.match_dyn`` is less efficient than ``re.match``, so if you
are matching against a fixed regex, you should use ``re.match``.
Example
``re.match_dyn(req.http.Cookie, beresp.http.X-Regex)``
backref backref
------- -------
...@@ -66,19 +94,25 @@ Returns ...@@ -66,19 +94,25 @@ Returns
String String
Description Description
Extracts the `nth` subexpression of the most recent successful Extracts the `nth` subexpression of the most recent successful
call to `re.match()` in the current session, or a fallback string call to ``re.match()`` or ``re.match_dyn`` in the same VCL
in case the extraction fails. Backref 0 indicates the full match. subroutine in the current session, or a fallback string in
Thus this function behaves like the `\\n` symbols in `regsub` case the extraction fails. Backref 0 indicates the entire
and `regsuball`, and the `$1`, `$2` ... variables in Perl. matched string. Thus this function behaves like the ``\\n``
symbols in ``regsub`` and ``regsuball``, and the ``$1``,
``$2`` ... variables in Perl.
After unsuccessful matches, the ``fallback`` string is returned
for any call to ``re.backref``.
After unsuccessful matches, the `fallback` string is returned The VCL infix operators ``~`` and ``!~`` do not affect this
for any call to `re.backref()`. function, nor do ``regsub`` or ``regsuball``.
The VCL infix operators `~` and `!~` do not affect this function, ``re.backref`` can extract up to 10 subexpressions, in
nor do `regsub` or `regsuball`. addition to to the full expression indicated by backref 0.
`re.backref` can extract up to 10 subexpressions, in addition to If ``re.backref`` is called without any prior call to
to the full expression indicated by backref 0. ``re.match`` or ``re.match_dyn`` in the same VCL subroutine,
then the result is undefined.
Example Example
``set beresp.ttl = std.duration(re.backref(1, "120"), 120s);`` ``set beresp.ttl = std.duration(re.backref(1, "120"), 120s);``
...@@ -90,7 +124,7 @@ Prototype ...@@ -90,7 +124,7 @@ Prototype
Returns Returns
string string
Description Description
Returns the string constant version-number of the header vmod. Returns the version string for this vmod.
Example Example
``set resp.http.X-re-version = re.version();`` ``set resp.http.X-re-version = re.version();``
...@@ -101,11 +135,11 @@ INSTALLATION ...@@ -101,11 +135,11 @@ INSTALLATION
Installation requires the Varnish source tree (only the source matching the Installation requires the Varnish source tree (only the source matching the
binary installation). binary installation).
1. `./autogen.sh` (for git-installation) 1. ``./autogen.sh`` (for git-installation)
2. `./configure VARNISHSRC=/path/to/your/varnish/source/varnish-cache` 2. ``./configure VARNISHSRC=/path/to/your/varnish/source/varnish-cache``
3. `make` 3. ``make``
4. `make install` (may require root: sudo make install) 4. ``make install`` (may require root: sudo make install)
5. `make check` (Optional for regression tests) 5. ``make check`` (Optional for regression tests)
VARNISHSRCDIR is the directory of the Varnish source tree for which to VARNISHSRCDIR is the directory of the Varnish source tree for which to
compile your vmod. Both the VARNISHSRCDIR and VARNISHSRCDIR/include compile your vmod. Both the VARNISHSRCDIR and VARNISHSRCDIR/include
...@@ -120,8 +154,10 @@ ACKNOWLEDGEMENTS ...@@ -120,8 +154,10 @@ ACKNOWLEDGEMENTS
================ ================
Author: Geoffrey Simmons <geoff@uplex.de>, UPLEX Nils Goroll Systemoptimierung. Author: Geoffrey Simmons <geoff@uplex.de>, UPLEX Nils Goroll Systemoptimierung.
The implementation was inspired by ideas from Nils Goroll's esicookies VMOD
and pmatch patch for Varnish 2, and by Kristian Lyngstøl's header VMOD. The implementation was inspired by ideas from Nils Goroll's esicookies
VMOD and pmatch patch for Varnish 2, and by Kristian Lyngstøl's header
VMOD.
HISTORY HISTORY
...@@ -130,12 +166,18 @@ HISTORY ...@@ -130,12 +166,18 @@ HISTORY
Version 0.1: Initial version Version 0.1: Initial version
BUGS LIMITATIONS
==== ===========
The regular expressions in ``re.match`` and ``re.match_dyn`` are
compiled at run-time, so there are no errors at VCL compile-time for
invalid expressions. If an expression is invalid, then an error
message is emitted to Varnish's shared memory log using the
``VCL_error`` tag, and the match always fails.
You can't use dynamic regular expressions, which also holds true for normal Regular expression matching is subject to the same limitations that
regular expressions in regsub(), but VCL isn't able to warn you about this hold for standard regexen in VCL, for example as set by the runtime
when it comes to vmods yet. parameters `pcre_match_limit` and `pcre_match_limit_recursion`.
SEE ALSO SEE ALSO
...@@ -143,11 +185,12 @@ SEE ALSO ...@@ -143,11 +185,12 @@ SEE ALSO
* varnishd(1) * varnishd(1)
* vcl(7) * vcl(7)
* pcre(3)
COPYRIGHT COPYRIGHT
========= =========
This document is licensed under the same license as the This document is licensed under the same license as the libvmod-re
libvmod-header project. See LICENSE for details. project. See LICENSE for details.
* Copyright (c) 2013 UPLEX Nils Goroll Systemoptimierung * Copyright (c) 2013 UPLEX Nils Goroll Systemoptimierung
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