Commit 1096b441 authored by Geoff Simmons's avatar Geoff Simmons

Doc updates and fixes.

- We write our own SYNOPSIS.
- Update Varnish version compatibility statement.
- Remove the reference to the pcre_* varnishd params in LIMITATIONS
  (no longer true).
- Spelling fix
parent 8640ee3a
......@@ -18,11 +18,27 @@ Varnish Module for Regular Expression Matching with Subexpression Capture
:Manual section: 3
SYNOPSIS
========
import re [from "path"] ;
::
import re;
# object interface
new <obj> = re.regex(STRING, [, INT limit] [, INT limit_recursion])
BOOL <obj>.match(STRING, [, INT limit] [, INT limit_recursion])
STRING <obj>.backref(INT [, STRING fallback])
# function interface
BOOL re.match_dyn(STRING, [, INT limit] [, INT limit_recursion])
STRING re.backref_dyn(INT [, STRING fallback])
STRING re.version()
DESCRIPTION
===========
......@@ -103,22 +119,19 @@ since it re-uses the compiled expression obtained at VCL
initialization. So if you are matching against a fixed pattern that
never changes during the lifetime of VCL, use ``match``.
CONTENTS
========
* regex(STRING, INT, INT)
* BOOL match_dyn(STRING, STRING, INT, INT)
* STRING backref_dyn(INT, STRING)
* STRING version()
.. _obj_regex:
regex
-----
new xregex = regex(STRING, INT limit, INT limit_recursion)
----------------------------------------------------------
::
new OBJ = regex(STRING, INT limit=1000, INT limit_recursion=1000)
new xregex = regex(
STRING,
INT limit=1000,
INT limit_recursion=1000
)
Description
Create a regex object with the given regular expression. The
......@@ -138,12 +151,12 @@ Example
.. _func_regex.match:
regex.match
-----------
BOOL xregex.match(STRING, INT limit, INT limit_recursion)
---------------------------------------------------------
::
BOOL regex.match(STRING, INT limit=0, INT limit_recursion=0)
BOOL xregex.match(STRING, INT limit=0, INT limit_recursion=0)
Description
Determines whether the given string matches the regex compiled
......@@ -152,14 +165,13 @@ Description
The optional parameter ``limit`` restricts the number of
internal matching function calls in a ``pcre_exec()``
execution, analoguous to the varnishd
``pcre_match_limit`` parameter. For the default
value 0, the ``limit`` given to the constructor `obj_regex`_
is used.
execution, analogous to the varnishd ``pcre_match_limit``
parameter. For the default value 0, the ``limit`` given to the
constructor `obj_regex`_ is used.
The optional parameter ``limit_recursion`` restricts the
number of internal matching function recursions in a
``pcre_exec()`` execution, analoguous to the varnishd
``pcre_exec()`` execution, analogous to the varnishd
``pcre_match_limit_recursion`` parameter. For the default
value 0, the ``limit_recursion`` given to the constructor
`obj_regex`_ is used.
......@@ -167,14 +179,18 @@ Description
Example
``if (myregex.match(beresp.http.Surrogate-Control)) { # ...``
.. _func_regex.backref:
regex.backref
-------------
STRING xregex.backref(INT, STRING fallback)
-------------------------------------------
::
STRING regex.backref(INT, STRING fallback="**BACKREF METHOD FAILED**")
STRING xregex.backref(
INT,
STRING fallback="**BACKREF METHOD FAILED**"
)
Description
Extracts the `nth` subexpression of the most recent successful
......@@ -200,14 +216,23 @@ Description
Example
``set beresp.ttl = std.duration(myregex.backref(1, "120"), 120s);``
.. _func_match_dyn:
match_dyn
---------
match_dyn(...)
--------------
::
BOOL match_dyn(STRING, STRING, INT limit=1000, INT limit_recursion=1000)
BOOL match_dyn(
STRING,
STRING,
INT limit=1000,
INT limit_recursion=1000
)
Description
Compiles the regular expression given in the first argument,
......@@ -226,14 +251,18 @@ Description
Example
``if (re.match_dyn(req.http.Foo + "(\d+)", beresp.http.Bar)) { # ...``
.. _func_backref_dyn:
backref_dyn
-----------
STRING backref_dyn(INT, STRING fallback)
----------------------------------------
::
STRING backref_dyn(INT, STRING fallback="**BACKREF FUNCTION FAILED**")
STRING backref_dyn(
INT,
STRING fallback="**BACKREF FUNCTION FAILED**"
)
Description
Similar to the ``backref`` method, this function extracts the
......@@ -249,14 +278,11 @@ Description
in the same task scope, then a ``VCL_Error`` message is logged, and
the fallback string is returned.
.. _func_version:
version
-------
::
.. _func_version:
STRING version()
STRING version()
----------------
Description
Returns the version string for this vmod.
......@@ -267,9 +293,9 @@ Example
REQUIREMENTS
============
The VMOD requires the Varnish master branch since commit a339f63. See
the project repository for versions that are compatible with other
versions of Varnish.
The VMOD requires the Varnish since version 6.0.0 or the master
branch. See the project repository for versions that are compatible
with other versions of Varnish.
INSTALLATION
============
......@@ -302,10 +328,6 @@ full expression indicated by backref 0. If a ``match`` or
(10 substrings and the full string), then a ``VCL_Error`` message is
emitted to the Varnish log, and the captures are limited to 11.
Regular expression matching is subject to the same limitations that
hold for standard regexen in VCL, for example as set by the runtime
parameters ``pcre_match_limit`` and ``pcre_match_limit_recursion``.
SEE ALSO
========
......@@ -315,6 +337,10 @@ SEE ALSO
* source repository: https://code.uplex.de/uplex-varnish/libvmod-re
COPYRIGHT
=========
......
......@@ -10,6 +10,26 @@
$Module re 3 Varnish Module for Regular Expression Matching with Subexpression Capture
$Synopsis manual
SYNOPSIS
========
::
import re;
# object interface
new <obj> = re.regex(STRING, [, INT limit] [, INT limit_recursion])
BOOL <obj>.match(STRING, [, INT limit] [, INT limit_recursion])
STRING <obj>.backref(INT [, STRING fallback])
# function interface
BOOL re.match_dyn(STRING, [, INT limit] [, INT limit_recursion])
STRING re.backref_dyn(INT [, STRING fallback])
STRING re.version()
DESCRIPTION
===========
......@@ -116,14 +136,13 @@ Description
The optional parameter ``limit`` restricts the number of
internal matching function calls in a ``pcre_exec()``
execution, analoguous to the varnishd
``pcre_match_limit`` parameter. For the default
value 0, the ``limit`` given to the constructor `obj_regex`_
is used.
execution, analogous to the varnishd ``pcre_match_limit``
parameter. For the default value 0, the ``limit`` given to the
constructor `obj_regex`_ is used.
The optional parameter ``limit_recursion`` restricts the
number of internal matching function recursions in a
``pcre_exec()`` execution, analoguous to the varnishd
``pcre_exec()`` execution, analogous to the varnishd
``pcre_match_limit_recursion`` parameter. For the default
value 0, the ``limit_recursion`` given to the constructor
`obj_regex`_ is used.
......@@ -205,9 +224,9 @@ Example
REQUIREMENTS
============
The VMOD requires the Varnish master branch since commit a339f63. See
the project repository for versions that are compatible with other
versions of Varnish.
The VMOD requires the Varnish since version 6.0.0 or the master
branch. See the project repository for versions that are compatible
with other versions of Varnish.
INSTALLATION
============
......@@ -240,10 +259,6 @@ full expression indicated by backref 0. If a ``match`` or
(10 substrings and the full string), then a ``VCL_Error`` message is
emitted to the Varnish log, and the captures are limited to 11.
Regular expression matching is subject to the same limitations that
hold for standard regexen in VCL, for example as set by the runtime
parameters ``pcre_match_limit`` and ``pcre_match_limit_recursion``.
SEE ALSO
========
......
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