Notice this facility is subject to change!

"regsub" is short for regular expression substitution and it is probably
easiest to explain with some examples:

	sub vcl_recv {
		set req.url = regsub(req.url, "#.*", "");
	}

This will replace the requests URL with the output of the regsub() function

regsub() takes three arguments: the string to be examined, a regular
expression and a replacement string.

In this case, everything after the first '#' is removed (replaced
with nothing).

The replacement string recognizes the following magic sequences:
	&	- insert everything matched by the regexp
	$0	- ditto.
	$1	- replace with the first submatch of the regexp
	$2	- replace with the second submatch of the regexp
	...
	$9	- replace with the ninth submatch of the regexp

(The $0..$9 syntax was chosen over the \0...\9 syntax in order to avoid
a nightmare of escape characters in the VCL source code.  Arguments and
suggestions are welcome).

A more advanced example:

	set bereq.http.ClientIP = regsub(client.ip, "(.*):(.*)", "$2 $1");

The client.ip variable expands to IP:port number, for instance
	127.0.0.1:54662

The regular expression "(.*):(.*)" results in the the following matches:
	& + $0		"127.0.0.1:54662"
	$1		"127.0.0.1"
	$2		"54662"

So the replacement string "$2 $1" results in "54662 127.0.0.1"

And the completed header which is sent to the backend will look like:

	"ClientIP: 54662 127.0.0.1"

An even more advanced example would be:

    set bereq.http.magic = "Client IP = " regsub(client.ip, ":", " port = ");

Where we also exploint the string concatenation ability of the "set" statement.

The result string is built in the request workspace, so you may need
to increase the workspace size if you do a lot of regsub()'s.

Currently there is no decent error handling for running out of workspace.


git-svn-id: http://www.varnish-cache.org/svn/trunk/varnish-cache@1667 d4fa192b-c00b-0410-8231-f00ffab90ce4