4 files changed, 123 insertions, 40 deletions

diff --git a/NEWS b/NEWS
index c700564..3ee8124 100644
--- a/NEWS
+++ b/NEWS
@@ -3,7 +3,7 @@ See the end of file for copying conditions.
 
 Please send vmod-dbrw bug reports to <gray@gnu.org>
 
-Version 2.2.91 (Git)
+Version 2.3, 2018-12-08
 
 * SQL idle timeout
 
diff --git a/configure.ac b/configure.ac
index 1212a37..420041e 100644
--- a/configure.ac
+++ b/configure.ac
@@ -14,7 +14,7 @@
 # You should have received a copy of the GNU General Public License
 # along with vmod-dbrw.  If not, see <http://www.gnu.org/licenses/>.
 AC_PREREQ(2.69)
-AC_INIT([vmod-dbrw], 2.2.91, [gray@gnu.org])
+AC_INIT([vmod-dbrw], 2.3, [gray@gnu.org])
 AC_CONFIG_AUX_DIR([build-aux])
 AC_CONFIG_MACRO_DIR([m4])
 AC_CONFIG_SRCDIR(src/vmod_dbrw.vcc)
@@ -43,7 +43,7 @@ AC_PROG_MAKE_SET
 AC_HEADER_STDC
 AC_CHECK_HEADERS([sys/stdlib.h])
 
-AM_VARNISHAPI([4.1],[5.1])
+AM_VARNISHAPI([4.1],[5.2.1])
 
 ###########
 # Check for SQL support       
diff --git a/doc/vmod-dbrw.3 b/doc/vmod-dbrw.3
index 4760b6b..21d15e2 100644
--- a/doc/vmod-dbrw.3
+++ b/doc/vmod-dbrw.3
@@ -298,7 +298,7 @@ sub vcl_synth {
 .\" for man-based doc pages.
 .if "\V[MANCGI]"WEBDOC" \{\
 .       ds package vmod-dbrw
-.       ds version 1.0
+.       ds version 2.2.91
 .       so download.inc
 \}
 .SH "SEE ALSO"
@@ -334,7 +334,7 @@ Sergey Poznyakoff
 .SH "BUG REPORTS"
 Report bugs to <gray@gnu.org>.
 .SH COPYRIGHT
-Copyright \(co 2013-2014 Sergey Poznyakoff
+Copyright \(co 2013-2018 Sergey Poznyakoff
 .br
 .na
 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
diff --git a/doc/vmod-dbrw.texi b/doc/vmod-dbrw.texi
index 31b15d1..734dadb 100644
--- a/doc/vmod-dbrw.texi
+++ b/doc/vmod-dbrw.texi
@@ -118,7 +118,7 @@ configuration file.
 
 Once the module is configured, the @code{rewrite} function can be called
 in the appropriate place of the Varnish configuration file.  Its argument
-is a list of variable assignments separated with semicolons, each
+is a list of variable assignments separated by semicolons, each
 assignment having the form @code{@var{name}=@var{value}}.  When called,
 @code{rewrite} expands the SQL query registered with the prior call to
 @code{config} by replacing each @code{$@var{name}}
@@ -127,11 +127,14 @@ construct (a @dfn{variable reference}) with the corresponding
 variable reference can also be written as @code{$@{@var{name}@}}.
 This latter form can be used in contexts where the variable reference is
 immediately followed by a letter, digit or underscore, to prevent it
-from being counted as a part of the name.
+from being counted as a part of the name. Special syntax is available
+for substituting default values and invoking built-in functions during
+the expansion of the query. @xref{Expansions}, for a detailed
+description of these.
 
-The expanded query is then sent to the database server.  If it returns
-a non-empty set, it is further handled depending on the number of
-fields it contains.
+Having undergone expansions, the query is sent to the database server.
+The returned set of records (if non-empty) is processed depending on the
+number of fields it contains.
 
 @cindex result interpretation
 @anchor{result interpretation}
@@ -155,7 +158,7 @@ treated as an extended POSIX regular expression.  If the value matches
 the expression, the @var{result} column is expanded by replacing
 @dfn{backreferences}: each occurrence of @code{$@var{digit}} (where
 @var{digit} stands for a decimal digit from @samp{0} through @samp{9})
-is replaced with the contents of the @var{digit}s parenthesized
+is replaced by the contents of the @var{digit}s parenthesized
 subexpression in @var{regexp}.  For compatibility with the traditional
 usage, the @code{\@var{digit}} notation is also allowed.  The
 resulting value is then returned to the caller.
@@ -234,12 +237,12 @@ Type of the database to use.  Valid values are @samp{mysql} and
 
 @item params
 Database connection parameters.  This is a list of
-@samp{@var{name}=@var{value}} assignments separated with semicolons.
+@samp{@var{name}=@var{value}} assignments separated by semicolons.
 The @var{value} part can be any sequence of characters, excepting
-white space and semicolon.  If any of these is to appear in it, they
-must either be escaped by prepending them with a backslash, or the
-entire @var{value} enclosed in a pair of (single or double) quotes.
-The following @dfn{escape sequences} are allowed for use in
+white space and semicolon.  If @var{value} contains any of these, they
+either must be escaped by prepending them with a backslash, or the
+entire @var{value} must be enclosed in a pair of (single or double)
+quotes. The following @dfn{escape sequences} are allowed for use in
 @var{value}:
 
 @cindex escape sequences
@@ -247,7 +250,7 @@ The following @dfn{escape sequences} are allowed for use in
 @float Table, backslash-interpretation
 @caption{Backslash escapes}
 @multitable @columnfractions 0.30 .5
-@item Sequence @tab Replaced with
+@item Sequence @tab Replaced by
 @item \a @tab Audible bell character (@acronym{ASCII} 7)
 @item \b @tab Backspace character (@acronym{ASCII} 8)
 @item \f @tab Form-feed character (@acronym{ASCII} 12)
@@ -258,8 +261,8 @@ The following @dfn{escape sequences} are allowed for use in
 @end multitable
 @end float
 
-If a backslash is followed by a symbol other than listed above, it
-is removed and the symbol following it is reproduced verbatim.
+If a backslash is immediately followed by a symbol not listed in the
+above table, it is removed and the symbol is reproduced verbatim.
 
 Valid parameters are:
 
@@ -344,15 +347,15 @@ Password to access the database.
 @kindex query
 @cindex database query
 @item query
-The SQL query to use.  It can contain variable references in the
-(@code{$@var{name}} or @code{$@{@var{name}@}}), which will be replaced
-with the actual value of the @var{name} argument to the function
-@code{rewrite}.
+The SQL query to use.  It can contain variable references 
+(@code{$@var{name}} or @code{$@{@var{name}@}}), which will be expanded
+to the actual value of the @var{name} argument to the function
+@code{rewrite}. @xref{Expansions}, for details.
 @end table
 @end deftypefn
 
 The example below configures @command{vmod-dbrw} to use MySQL database
-@samp{rewrite}, with the user name @samp{varnish} and password @var{guessme}.
+@samp{rewrite}, with the user name @samp{varnish} and password @samp{guessme}.
 
 @example
 @group
@@ -369,13 +372,92 @@ sub vcl_recv @{
 @end group
 @end example
 
+@menu
+* Expansions::
+@end menu
+
+@node Expansions
+@section Expansions
+@cindex expansions
+@cindex variable expansion
+@cindex expansion, variable
+  The @samp{query} argument to the @code{dbrw.config} function
+normally contains variable references.  A variable reference has the
+form @samp{$@var{variable}} or @samp{$@{@var{variable}@}}, where
+@var{variable} is the variable name.  When the @code{dbrw.rewrite}
+function (@pxref{Rewrite}) is called, each such reference is expanded
+to the actual value of @var{variable} passed in the argument to that
+function.
+
+The two forms are entirely equivalent.  The form with curly braces is
+normally used if the variable name is immediately followed by an
+alphanumeric symbol, which will otherwise be considered a part of it.
+This form also allows for specifying the action to take if the
+variable is undefined or expands to an empty value. 
+
+During variable expansion, the forms below cause @code{dbrw.rewrite}
+to test for a variable that is unset or null (i.e., whose value is an
+empty string).  Omitting the colon results in a test only for a
+variable that is unset.
+
+@table @asis
+@item $@{@var{variable}:-@var{word}@}
+@dfn{Use Default Values}.  If @var{variable} is unset or null, the expansion
+of @var{word} is  substituted.   Otherwise, the value of @var{variable} is
+substituted.
+
+@item $@{@var{variable}:=@var{word}@}
+@dfn{Assign Default Values}.  If @var{variable} is unset or null, the
+expansion  of @var{word} is assigned to variable.  The value of 
+@var{variable} is then substituted.
+                            
+@item $@{@var{variable}:?@var{word}@}
+@dfn{Display Error if Null or Unset}.  If @var{variable} is null or unset,
+the expansion of @var{word} (or a message to that effect if @var{word} is
+not present) is output to the current logging channel.  Otherwise, the
+value of @var{variable} is substituted.
+
+@item $@{@var{variable}:+@var{word}@}