Use vmod-dbrw (with a dash) as the canonical project name.

13 files changed, 486 insertions, 469 deletions

diff --git a/Makefile.am b/Makefile.am
index 829c138..fa15223 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,5 +1,5 @@
-# This file is part of libvmod_dbrw
+# This file is part of vmod-dbrw
 # Copyright (C) 2013 Sergey Poznyakoff
 #
-# Libvmod_dbrw is free software; you can redistribute it and/or modify
+# Vmod-dbrw is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -8,3 +8,3 @@
 #
-# Libvmod_dbrw is distributed in the hope that it will be useful,
+# Vmod-dbrw is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
@@ -14,3 +14,3 @@
 # You should have received a copy of the GNU General Public License
-# along with libvmod_dbrw.  If not, see <http://www.gnu.org/licenses/>.
+# along with vmod-dbrw.  If not, see <http://www.gnu.org/licenses/>.
 ACLOCAL_AMFLAGS = -I m4
diff --git a/configure.ac b/configure.ac
index d5a8767..a287eb3 100644
--- a/configure.ac
+++ b/configure.ac
@@ -1,5 +1,5 @@
-# This file is part of libvmod_dbrw -*- autoconf -*-
+# This file is part of vmod-dbrw -*- autoconf -*-
 # Copyright (C) 2013 Sergey Poznyakoff
 #
-# Libvmod_dbrw is free software; you can redistribute it and/or modify
+# Vmod-dbrw is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -8,3 +8,3 @@
 #
-# Libvmod_dbrw is distributed in the hope that it will be useful,
+# Vmod-dbrw is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
@@ -14,5 +14,5 @@
 # You should have received a copy of the GNU General Public License
-# along with libvmod_dbrw.  If not, see <http://www.gnu.org/licenses/>.
+# along with vmod-dbrw.  If not, see <http://www.gnu.org/licenses/>.
 AC_PREREQ(2.69)
-AC_INIT([libvmod-dbrw], 0.99, [gray@gnu.org])
+AC_INIT([vmod-dbrw], 0.99, [gray@gnu.org])
 AC_CONFIG_AUX_DIR([build-aux])
diff --git a/doc/.gitignore b/doc/.gitignore
index 4e23977..ddb72ba 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -3,17 +3,17 @@ stamp-vti
 version.texi
-vmod_dbrw.info*
-vmod_dbrw.aux
-vmod_dbrw.cp
-vmod_dbrw.cps
-vmod_dbrw.fn
-vmod_dbrw.kw
-vmod_dbrw.ky
-vmod_dbrw.log
-vmod_dbrw.op
-vmod_dbrw.pdf
-vmod_dbrw.pg
-vmod_dbrw.toc
-vmod_dbrw.tp
-vmod_dbrw.vr
-vmod_dbrw.t2p
+vmod-dbrw.info*
+vmod-dbrw.aux
+vmod-dbrw.cp
+vmod-dbrw.cps
+vmod-dbrw.fn
+vmod-dbrw.kw
+vmod-dbrw.ky
+vmod-dbrw.log
+vmod-dbrw.op
+vmod-dbrw.pdf
+vmod-dbrw.pg
+vmod-dbrw.toc
+vmod-dbrw.tp
+vmod-dbrw.vr
+vmod-dbrw.t2p
 manual
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 9e03e8a..88cf24b 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,3 +1,19 @@
-dist_man_MANS = vmod_dbrw.3
-info_TEXINFOS=vmod_dbrw.texi
+# This file is part of vmod-dbrw
+# Copyright (C) 2013 Sergey Poznyakoff
+#
+# Vmod-dbrw is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3, or (at your option)
+# any later version.
+#
+# Vmod-dbrw is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with vmod-dbrw.  If not, see <http://www.gnu.org/licenses/>.
+
+dist_man_MANS = vmod-dbrw.3 vmod_dbrw.3
+info_TEXINFOS=vmod-dbrw.texi
 vmod_dbrw_TEXINFOS=fdl.texi
@@ -21,3 +37,3 @@ manual:
          TEXI2HTML="texi2html $(AM_MAKEINFOFLAGS)" \
-         $(GENDOCS) --texi2html vmod_dbrw 'Vmod_dbrw manual'
+         $(GENDOCS) --texi2html $(PACKAGE) '$(PACKAGE_NAME) manual'
 
diff --git a/doc/vmod-dbrw.3 b/doc/vmod-dbrw.3
new file mode 100644
index 0000000..9c35772
--- /dev/null
+++ b/doc/vmod-dbrw.3
@@ -0,0 +1,402 @@
+.\" This file is part of Vmod-dbrw -*- nroff -*-
+.\" Copyright (C) 2013 Sergey Poznyakoff
+.\"
+.\" Vmod-dbrw is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" Vmod-dbrw is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with vmod-dbrw.  If not, see <http://www.gnu.org/licenses/>.
+.TH VMOD_DBRW 1 "July 19, 2013" "VMOD_DBRW" "User Reference"
+.SH NAME
+vmod-dbrw \- Database-driven rewrite rules for Varnish Cache
+.SH SYNOPSIS
+.sp
+.nf
+import dbrw;
+
+sub vcl_init {
+    dbrw.config("\fIDBTYPE\fR", "\fIPARAMS\fR", "\fIQUERY\fR");
+}
+
+sub vcl_recv {
+    set req.http.\fIXHEADER\fR = dbrw.rewrite(\fIARGS\fR);
+    if (req.http.\fIXHEADER\fR) {
+        error(750, "Redirect");
+    }
+}
+
+sub vcl_error {
+    if (obj.status == 750) {
+        set obj.http.Location = req.http.\fIXHEADER\fR;
+        set obj.status = 301;
+        return (deliver);
+    }
+}
+.fi
+.SH DESCRIPTION
+.B Vmod-dbrw
+is a Varnish Cache module implementing database-driven rewrite procedures.
+Its intended use is for web sites that need an exceedingly big number
+of redirect and/or rewrite rules.
+.PP
+Upon startup, the \fBconfig\fR function should be called.  This call
+configures the module and supplies it the information necessary for
+accessing the database and interpreting the data obtained from it.
+.PP
+Two database types are supported: \fBMySQL\fR or \fBPostgreSQL\fR.
+The first argument \fBconfig\fR instructs the module which type to
+use.
+.PP
+.B Vmod-dbrw
+does not impose any requirements on the structure of the database,
+therefore the connection arguments and access credentials may vary
+depending on the flavor of the database used.  This information is
+supplied in the \fIPARAMS\fR argument, which is a list of parameter
+assignments separated with semicolons.
+.PP
+Once configured, the \fBrewrite\fR function can be called in the
+appropriate place of the Varnish configuration file.  Its argument
+\fIARGS\fR is a list of variable assignments separated with
+semicolons, similarly to the \fIPARAMS\fR argument described above.
+Each assignment has the form \fINAME\fB=\fIVALUE\fR.  When called
+the function expands the \fBSQL\fR query, supplied with the \fIQUERY\fR
+argument to the \fBconfig\fR call, by replacing each \fB$\fINAME\fR
+construct (a \fBvariable reference\fR) with the corresponding
+\fIVALUE\fR from its argument.  Similarly to the shell syntax, the
+variable reference can be written as \fB${\fINAME\fB}\fR.  This latter
+form can be used in contexts where the variable name is immediately
+followed by another letter, to prevent it from being counted as a part
+of the name.
+.PP
+The expanded query is then sent to the database server.  The handling
+of the return value depends on the number of fields it contains.
+.SS Strict matches
+If the returned set consists of one or two columns, only the
+first tuple is used and the value of its first column is returned.
+The second column (if present) is ignored.
+.SS Regexp matches
+Otherwise, if the returned set consists of three or four columns, the
+columns are interpreted as follows: \fBresult\fR, \fBregexp\fR,
+\fBvalue\fR and optional \fBflags\fR.  For each returned tuple, the
+\fBvalue\fR column undergoes variable expansion, using the same
+algorithm as when preparing the query, and the resulting string is
+matched with the \fBregexp\fR column, which is treated as an extended
+\fBPOSIX\fR regular expression.  If the match occurs, the \fBresult\fR
+column is expanded by replacing \fBbackreferences\fR.  Each occurrence
+of \fB$\fIDIGIT\fR (where \fIDIGIT\fR stands for a decimal digit from
+\fB0\fR through \fB9\fR) is replaced with the contents of the
+\fIDIGIT\fR's parenthesized subexpression in \fBregexp\fR.  For
+compatibility with the traditional usage, the \fB\\\fIDIGIT\fR
+notation is also allowed.  The resulting value is returned.
+.PP
+Optional \fBflags\fR column is a comma-separated list of flags that
+modify regular expression handling.  The following flags are defined:
+.TP
+.BR NC " or " nocase
+Treat \fBregexp\fR as case-insensitive.
+.TP