X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FSQL%2FAbstract.pm;h=93641289c9dc790f9e54b224f2e945c6ab154455;hb=ce3bc4b0f271bfff9032c9279cc1b2688bbe67c5;hp=f4d4c0bd597eca78f869ea5b4b6ee96a0639166a;hpb=27fa2a14ad5d889570cf3edc42a031050046ffbc;p=scpubgit%2FQ-Branch.git

diff --git a/lib/SQL/Abstract.pm b/lib/SQL/Abstract.pm
index f4d4c0b..9364128 100644
--- a/lib/SQL/Abstract.pm
+++ b/lib/SQL/Abstract.pm
@@ -27,7 +27,7 @@ BEGIN {
 # GLOBALS
 #======================================================================
 
-our $VERSION  = '1.82';
+our $VERSION  = '1.86';
 
 # This would confuse some packagers
 $VERSION = eval $VERSION if $VERSION =~ /_/; # numify for warning-free dev releases
@@ -219,7 +219,7 @@ sub insert {
   $sql = join " ", $self->_sqlcase('insert into'), $table, $sql;
 
   if ($options->{returning}) {
-    my ($s, @b) = $self->_insert_returning ($options);
+    my ($s, @b) = $self->_insert_returning($options);
     $sql .= $s;
     push @bind, @b;
   }
@@ -227,7 +227,8 @@ sub insert {
   return wantarray ? ($sql, @bind) : $sql;
 }
 
-# Used by DBIx::Class::SQLMaker->insert
+# So that subclasses can override INSERT ... RETURNING separately from
+# UPDATE and DELETE (e.g. DBIx::Class::SQLMaker::Oracle does this)
 sub _insert_returning { shift->_returning(@_) }
 
 sub _returning {
@@ -329,7 +330,7 @@ sub _insert_value {
       push @all_bind, @bind;
     },
 
-    # THINK : anything useful to do with a HASHREF ?
+    # THINK: anything useful to do with a HASHREF ?
     HASHREF => sub {       # (nothing, but old SQLA passed it through)
       #TODO in SQLA >= 2.0 it will die instead
       belch "HASH ref as bind value in insert is not supported";
@@ -367,10 +368,32 @@ sub update {
   my $options = shift;
 
   # first build the 'SET' part of the sql statement
-  my (@set, @all_bind);
   puke "Unsupported data type specified to \$sql->update"
     unless ref $data eq 'HASH';
 
+  my ($sql, @all_bind) = $self->_update_set_values($data);
+  $sql = $self->_sqlcase('update ') . $table . $self->_sqlcase(' set ')
+          . $sql;
+
+  if ($where) {
+    my($where_sql, @where_bind) = $self->where($where);
+    $sql .= $where_sql;
+    push @all_bind, @where_bind;
+  }
+
+  if ($options->{returning}) {
+    my ($returning_sql, @returning_bind) = $self->_update_returning($options);
+    $sql .= $returning_sql;
+    push @all_bind, @returning_bind;
+  }
+
+  return wantarray ? ($sql, @all_bind) : $sql;
+}
+
+sub _update_set_values {
+  my ($self, $data) = @_;
+
+  my (@set, @all_bind);
   for my $k (sort keys %$data) {
     my $v = $data->{$k};
     my $r = ref $v;
@@ -405,7 +428,7 @@ sub update {
           if (@rest or not $op =~ /^\-(.+)/);
 
         local $self->{_nested_func_lhs} = $k;
-        my ($sql, @bind) = $self->_where_unary_op ($1, $arg);
+        my ($sql, @bind) = $self->_where_unary_op($1, $arg);
 
         push @set, "$label = $sql";
         push @all_bind, @bind;
@@ -418,24 +441,13 @@ sub update {
   }
 
   # generate sql
-  my $sql = $self->_sqlcase('update') . " $table " . $self->_sqlcase('set ')
-          . join ', ', @set;
+  my $sql = join ', ', @set;
 
-  if ($where) {
-    my($where_sql, @where_bind) = $self->where($where);
-    $sql .= $where_sql;
-    push @all_bind, @where_bind;
-  }
-
-  if ($options->{returning}) {
-    my ($returning_sql, @returning_bind) = $self->_update_returning ($options);
-    $sql .= $returning_sql;
-    push @all_bind, @returning_bind;
-  }
-
-  return wantarray ? ($sql, @all_bind) : $sql;
+  return ($sql, @all_bind);
 }
 
+# So that subclasses can override UPDATE ... RETURNING separately from
+# INSERT and DELETE
 sub _update_returning { shift->_returning(@_) }
 
 
@@ -452,34 +464,52 @@ sub select {
   my $where  = shift;
   my $order  = shift;
 
-  my($where_sql, @bind) = $self->where($where, $order);
+  my ($fields_sql, @bind) = $self->_select_fields($fields);
 
-  my $f = (ref $fields eq 'ARRAY') ? join ', ', map { $self->_quote($_) } @$fields
-                                   : $fields;
-  my $sql = join(' ', $self->_sqlcase('select'), $f,
+  my ($where_sql, @where_bind) = $self->where($where, $order);
+  push @bind, @where_bind;
+
+  my $sql = join(' ', $self->_sqlcase('select'), $fields_sql,
                       $self->_sqlcase('from'),   $table)
           . $where_sql;
 
   return wantarray ? ($sql, @bind) : $sql;
 }
 
+sub _select_fields {
+  my ($self, $fields) = @_;
+  return ref $fields eq 'ARRAY' ? join ', ', map { $self->_quote($_) } @$fields
+                                : $fields;
+}
+
 #======================================================================
 # DELETE
 #======================================================================
 
 
 sub delete {
-  my $self  = shift;
-  my $table = $self->_table(shift);
-  my $where = shift;
-
+  my $self    = shift;
+  my $table   = $self->_table(shift);
+  my $where   = shift;
+  my $options = shift;
 
   my($where_sql, @bind) = $self->where($where);
-  my $sql = $self->_sqlcase('delete from') . " $table" . $where_sql;
+  my $sql = $self->_sqlcase('delete from ') . $table . $where_sql;
+
+  if ($options->{returning}) {
+    my ($returning_sql, @returning_bind) = $self->_delete_returning($options);
+    $sql .= $returning_sql;
+    push @bind, @returning_bind;
+  }
 
   return wantarray ? ($sql, @bind) : $sql;
 }
 
+# So that subclasses can override DELETE ... RETURNING separately from
+# INSERT and UPDATE
+sub _delete_returning { shift->_returning(@_) }
+
+
 
 #======================================================================
 # WHERE: entry point
@@ -493,7 +523,7 @@ sub where {
 
   # where ?
   my ($sql, @bind) = $self->_recurse_where($where);
-  $sql = $sql ? $self->_sqlcase(' where ') . "( $sql )" : '';
+  $sql = (defined $sql and length $sql) ? $self->_sqlcase(' where ') . "( $sql )" : '';
 
   # order by?
   if ($order) {
@@ -505,14 +535,65 @@ sub where {
   return wantarray ? ($sql, @bind) : $sql;
 }
 
+sub _expand_expr {
+  my ($self, $expr, $logic) = @_;
+  if (ref($expr) eq 'HASH') {
+    if (keys %$expr > 1) {
+      $logic ||= 'and';
+      return +{ "-${logic}" => [
+        map $self->_expand_expr_hashpair($_ => $expr->{$_}, $logic),
+          sort keys %$expr
+      ] };
+    }
+    return $self->_expand_expr_hashpair(%$expr, $logic);
+  }
+  return $expr;
+}
+
+sub _expand_expr_hashpair {
+  my ($self, $k, $v, $logic) = @_;
+  if ($k =~ /^-/) {
+    if ($k eq '-nest') {
+      return $self->_expand_expr($v);
+    }
+    if (my ($rest) = $k =~/^-not[_ ](.*)$/) {
+      return $self->_expand_expr({ -not => { "-${rest}", $v } }, $logic);
+    }
+  } else {
+    if (!ref($v)) {
+      return +{ $k => { $self->{cmp} => $v } };
+    }
+    if (ref($v) eq 'ARRAY') {
+      return $self->{sqlfalse} unless @$v;
+      $self->_debug("ARRAY($k) means distribute over elements");
+      my $this_logic = (
+        $v->[0] =~ /^-((?:and|or))$/i
+          ? ($v = [ @{$v}[1..$#$v] ], $1)
+          : ($self->{logic} || 'or')
+      );
+      return +{ "-${this_logic}" => [ map $self->_expand_expr({ $k => $_ }, $this_logic), @$v ] };
+    }
+    if (my $literal = is_literal_value($v)) {
+      unless (length $k) {
+        belch 'Hash-pairs consisting of an empty string with a literal are deprecated, and will be removed in 2.0: use -and => [ $literal ] instead';
+        return \$literal;
+      }
+      my ($sql, @bind) = @$literal;
+      return \[ $self->_quote($k).' '.$sql, @bind ];
+    }
+  }
+  return { $k => $v };
+}
 
 sub _recurse_where {
   my ($self, $where, $logic) = @_;
 
+  my $where_exp = $self->_expand_expr($where, $logic);
+
   # dispatch on appropriate method according to refkind of $where
-  my $method = $self->_METHOD_FOR_refkind("_where", $where);
+  my $method = $self->_METHOD_FOR_refkind("_where", $where_exp);
 
-  my ($sql, @bind) =  $self->$method($where, $logic);
+  my ($sql, @bind) =  $self->$method($where_exp, $logic);
 
   # DBIx::Class used to call _recurse_where in scalar context
   # something else might too...
@@ -615,7 +696,7 @@ sub _where_HASHREF {
         $op =~ s/^not_/NOT /i;
 
         $self->_debug("Unary OP(-$op) within hashref, recursing...");
-        my ($s, @b) = $self->_where_unary_op ($op, $v);
+        my ($s, @b) = $self->_where_unary_op($op, $v);
 
         # top level vs nested
         # we assume that handled unary ops will take care of their ()s
@@ -654,9 +735,9 @@ sub _where_unary_op {
   # top level special ops are illegal in general
   # this includes the -ident/-value ops (dual purpose unary and special)
   puke "Illegal use of top-level '-$op'"
-    if ! defined $self->{_nested_func_lhs} and List::Util::first {$op =~ $_->{regex}} @{$self->{special_ops}};
+    if ! defined $self->{_nested_func_lhs} and List::Util::first { $op =~ $_->{regex} } @{$self->{special_ops}};
 
-  if (my $op_entry = List::Util::first {$op =~ $_->{regex}} @{$self->{unary_ops}}) {
+  if (my $op_entry = List::Util::first { $op =~ $_->{regex} } @{$self->{unary_ops}}) {
     my $handler = $op_entry->{handler};
 
     if (not ref $handler) {
@@ -664,7 +745,7 @@ sub _where_unary_op {
         belch 'Use of [and|or|nest]_N modifiers is deprecated and will be removed in SQLA v2.0. '
             . "You probably wanted ...-and => [ -$op => COND1, -$op => COND2 ... ]";
       }
-      return $self->$handler ($op, $rhs);
+      return $self->$handler($op, $rhs);
     }
     elsif (ref $handler eq 'CODE') {
       return $handler->($self, $op, $rhs);
@@ -678,7 +759,7 @@ sub _where_unary_op {
 
   $self->_assert_pass_injection_guard($op);
 
-  my ($sql, @bind) = $self->_SWITCH_refkind ($rhs, {
+  my ($sql, @bind) = $self->_SWITCH_refkind($rhs, {
     SCALAR =>   sub {
       puke "Illegal use of top-level '-$op'"
         unless defined $self->{_nested_func_lhs};
@@ -689,11 +770,11 @@ sub _where_unary_op {
       );
     },
     FALLBACK => sub {
-      $self->_recurse_where ($rhs)
+      $self->_recurse_where($rhs)
     },
   });
 
-  $sql = sprintf ('%s %s',
+  $sql = sprintf('%s %s',
     $self->_sqlcase($op),
     $sql,
   );
@@ -710,8 +791,8 @@ sub _where_op_ANDOR {
     },
 
     HASHREF => sub {
-      return ( $op =~ /^or/i )
-        ? $self->_where_ARRAYREF( [ map { $_ => $v->{$_} } ( sort keys %$v ) ], $op )
+      return ($op =~ /^or/i)
+        ? $self->_where_ARRAYREF([ map { $_ => $v->{$_} } (sort keys %$v) ], $op)
         : $self->_where_HASHREF($v);
     },
 
@@ -757,7 +838,7 @@ sub _where_op_NEST {
     },
 
     FALLBACK => sub {
-      $self->_recurse_where ($v);
+      $self->_recurse_where($v);
     },
 
    });
@@ -777,7 +858,7 @@ sub _where_op_BOOL {
     },
 
     FALLBACK => sub {
-      $self->_recurse_where ($v);
+      $self->_recurse_where($v);
     },
   });
 
@@ -814,14 +895,14 @@ sub _where_op_VALUE {
   # special-case NULL
   if (! defined $rhs) {
     return defined $lhs
-      ? $self->_convert($self->_quote($lhs)) . ' IS NULL'
+      ? $self->_where_hashpair_HASHREF($lhs, { -is => undef })
       : undef
     ;
   }
 
   my @bind =
-    $self->_bindtype (
-      ( defined $lhs ? $lhs : $self->{_nested_func_lhs} ),
+    $self->_bindtype(
+      (defined $lhs ? $lhs : $self->{_nested_func_lhs}),
       $rhs,
     )
   ;
@@ -841,7 +922,7 @@ sub _where_op_VALUE {
 sub _where_hashpair_ARRAYREF {
   my ($self, $k, $v) = @_;
 
-  if( @$v ) {
+  if (@$v) {
     my @v = @$v; # need copy because of shift below
     $self->_debug("ARRAY($k) means distribute over elements");
 
@@ -906,17 +987,17 @@ sub _where_hashpair_HASHREF {
     my ($sql, @bind);
 
     # CASE: col-value logic modifiers
-    if ( $orig_op =~ /^ \- (and|or) $/xi ) {
+    if ($orig_op =~ /^ \- (and|or) $/xi) {
       ($sql, @bind) = $self->_where_hashpair_HASHREF($k, $val, $1);
     }
     # CASE: special operators like -in or -between
-    elsif ( my $special_op = List::Util::first {$op =~ $_->{regex}} @{$self->{special_ops}} ) {
+    elsif (my $special_op = List::Util::first { $op =~ $_->{regex} } @{$self->{special_ops}}) {
       my $handler = $special_op->{handler};
       if (! $handler) {
         puke "No handler supplied for special operator $orig_op";
       }
       elsif (not ref $handler) {
-        ($sql, @bind) = $self->$handler ($k, $op, $val);
+        ($sql, @bind) = $self->$handler($k, $op, $val);
       }
       elsif (ref $handler eq 'CODE') {
         ($sql, @bind) = $handler->($self, $k, $op, $val);
@@ -954,9 +1035,9 @@ sub _where_hashpair_HASHREF {
         },
 
         FALLBACK => sub {       # CASE: col => {op/func => $stuff}
-          ($sql, @bind) = $self->_where_unary_op ($op, $val);
+          ($sql, @bind) = $self->_where_unary_op($op, $val);
 
-          $sql = join (' ',
+          $sql = join(' ',
             $self->_convert($self->_quote($k)),
             $self->{_nested_func_lhs} eq $k ? $sql : "($sql)",  # top level vs nested
           );
@@ -992,15 +1073,15 @@ sub _where_field_op_ARRAYREF {
 
   my @vals = @$vals;  #always work on a copy
 
-  if(@vals) {
+  if (@vals) {
     $self->_debug(sprintf '%s means multiple elements: [ %s ]',
       $vals,
-      join (', ', map { defined $_ ? "'$_'" : 'NULL' } @vals ),
+      join(', ', map { defined $_ ? "'$_'" : 'NULL' } @vals ),
     );
 
     # see if the first element is an -and/-or op
     my $logic;
-    if (defined $vals[0] && $vals[0] =~ /^ - ( AND|OR ) $/ix) {
+    if (defined $vals[0] && $vals[0] =~ /^ - (AND|OR) $/ix) {
       $logic = uc $1;
       shift @vals;
     }
@@ -1013,7 +1094,7 @@ sub _where_field_op_ARRAYREF {
         and
       (!$logic or $logic eq 'OR')
         and
-      ( $op =~ $self->{inequality_op} or $op =~ $self->{not_like_op} )
+      ($op =~ $self->{inequality_op} or $op =~ $self->{not_like_op})
     ) {
       my $o = uc($op);
       belch "A multi-element arrayref as an argument to the inequality op '$o' "
@@ -1059,19 +1140,14 @@ sub _where_hashpair_ARRAYREFREF {
 sub _where_hashpair_SCALAR {
   my ($self, $k, $v) = @_;
   $self->_debug("NOREF($k) means simple key=val: $k $self->{cmp} $v");
-  my $sql = join ' ', $self->_convert($self->_quote($k)),
-                      $self->_sqlcase($self->{cmp}),
-                      $self->_convert('?');
-  my @bind =  $self->_bindtype($k, $v);
-  return ( $sql, @bind);
+  return ($self->_where_hashpair_HASHREF($k, { $self->{cmp} => $v }));
 }
 
 
 sub _where_hashpair_UNDEF {
   my ($self, $k, $v) = @_;
   $self->_debug("UNDEF($k) means IS NULL");
-  my $sql = $self->_quote($k) . $self->_sqlcase(' is null');
-  return ($sql);
+  return $self->_where_hashpair_HASHREF($k, { -is => undef });
 }
 
 #======================================================================
@@ -1147,9 +1223,9 @@ sub _where_field_BETWEEN {
            },
            HASHREF => sub {
              my ($func, $arg, @rest) = %$val;
-             puke ("Only simple { -func => arg } functions accepted as sub-arguments to BETWEEN")
+             puke "Only simple { -func => arg } functions accepted as sub-arguments to BETWEEN"
                if (@rest or $func !~ /^ \- (.+)/x);
-             $self->_where_unary_op ($1 => $arg);
+             $self->_where_unary_op($1 => $arg);
            },
            FALLBACK => sub {
              puke $invalid_args,
@@ -1177,7 +1253,7 @@ sub _where_field_BETWEEN {
 sub _where_field_IN {
   my ($self, $k, $op, $vals) = @_;
 
-  # backwards compatibility : if scalar, force into an arrayref
+  # backwards compatibility: if scalar, force into an arrayref
   $vals = [$vals] if defined $vals && ! ref $vals;
 
   my ($label)       = $self->_convert($self->_quote($k));
@@ -1204,9 +1280,9 @@ sub _where_field_IN {
             },
             HASHREF => sub {
               my ($func, $arg, @rest) = %$val;
-              puke ("Only simple { -func => arg } functions accepted as sub-arguments to IN")
+              puke "Only simple { -func => arg } functions accepted as sub-arguments to IN"
                 if (@rest or $func !~ /^ \- (.+)/x);
-              $self->_where_unary_op ($1 => $arg);
+              $self->_where_unary_op($1 => $arg);
             },
             UNDEF => sub {
               puke(
@@ -1222,28 +1298,28 @@ sub _where_field_IN {
         }
 
         return (
-          sprintf ('%s %s ( %s )',
+          sprintf('%s %s ( %s )',
             $label,
             $op,
-            join (', ', @all_sql)
+            join(', ', @all_sql)
           ),
           $self->_bindtype($k, @all_bind),
         );
       }
-      else { # empty list : some databases won't understand "IN ()", so DWIM
+      else { # empty list: some databases won't understand "IN ()", so DWIM
         my $sql = ($op =~ /\bnot\b/i) ? $self->{sqltrue} : $self->{sqlfalse};
         return ($sql);
       }
     },
 
     SCALARREF => sub {  # literal SQL
-      my $sql = $self->_open_outer_paren ($$vals);
+      my $sql = $self->_open_outer_paren($$vals);
       return ("$label $op ( $sql )");
     },
     ARRAYREFREF => sub {  # literal SQL with bind
       my ($sql, @bind) = @$$vals;
       $self->_assert_bindval_matches_bindtype(@bind);
-      $sql = $self->_open_outer_paren ($sql);
+      $sql = $self->_open_outer_paren($sql);
       return ("$label $op ( $sql )", @bind);
     },
 
@@ -1265,17 +1341,17 @@ sub _where_field_IN {
 sub _open_outer_paren {
   my ($self, $sql) = @_;
 
-  while ( my ($inner) = $sql =~ /^ \s* \( (.*) \) \s* $/xs ) {
+  while (my ($inner) = $sql =~ /^ \s* \( (.*) \) \s* $/xs) {
 
     # there are closing parens inside, need the heavy duty machinery
     # to reevaluate the extraction starting from $sql (full reevaluation)
-    if ( $inner =~ /\)/ ) {
+    if ($inner =~ /\)/) {
       require Text::Balanced;
 
       my (undef, $remainder) = do {
         # idiotic design - writes to $@ but *DOES NOT* throw exceptions
         local $@;
-        Text::Balanced::extract_bracketed( $sql, '()', qr/\s*/ );
+        Text::Balanced::extract_bracketed($sql, '()', qr/\s*/);
       };
 
       # the entire expression needs to be a balanced bracketed thing
@@ -1298,17 +1374,17 @@ sub _order_by {
   my ($self, $arg) = @_;
 
   my (@sql, @bind);
-  for my $c ($self->_order_by_chunks ($arg) ) {
-    $self->_SWITCH_refkind ($c, {
+  for my $c ($self->_order_by_chunks($arg) ) {
+    $self->_SWITCH_refkind($c, {
       SCALAR => sub { push @sql, $c },
       ARRAYREF => sub { push @sql, shift @$c; push @bind, @$c },
     });
   }
 
   my $sql = @sql
-    ? sprintf ('%s %s',
+    ? sprintf('%s %s',
         $self->_sqlcase(' order by'),
-        join (', ', @sql)
+        join(', ', @sql)
       )
     : ''
   ;
@@ -1322,7 +1398,7 @@ sub _order_by_chunks {
   return $self->_SWITCH_refkind($arg, {
 
     ARRAYREF => sub {
-      map { $self->_order_by_chunks ($_ ) } @$arg;
+      map { $self->_order_by_chunks($_ ) } @$arg;
     },
 
     ARRAYREFREF => sub {
@@ -1343,17 +1419,17 @@ sub _order_by_chunks {
 
       return () unless $key;
 
-      if ( @rest or not $key =~ /^-(desc|asc)/i ) {
+      if (@rest or not $key =~ /^-(desc|asc)/i) {
         puke "hash passed to _order_by must have exactly one key (-desc or -asc)";
       }
 
       my $direction = $1;
 
       my @ret;
-      for my $c ($self->_order_by_chunks ($val)) {
+      for my $c ($self->_order_by_chunks($val)) {
         my ($sql, @bind);
 
-        $self->_SWITCH_refkind ($c, {
+        $self->_SWITCH_refkind($c, {
           SCALAR => sub {
             $sql = $c;
           },
@@ -1411,7 +1487,7 @@ sub _quote {
   my $esc = $_[0]->{escape_char} || $r;
 
   # parts containing * are naturally unquoted
-  return join( $_[0]->{name_sep}||'', map
+  return join($_[0]->{name_sep}||'', map
     +( $_ eq '*' ? $_ : do { (my $n = $_) =~ s/(\Q$esc\E|\Q$r\E)/$esc$1/g; $l . $n . $r } ),
     ( $_[0]->{name_sep} ? split (/\Q$_[0]->{name_sep}\E/, $_[1] ) : $_[1] )
   );
@@ -1554,7 +1630,7 @@ sub values {
         unless ref $data eq 'HASH';
 
     my @all_bind;
-    foreach my $k ( sort keys %$data ) {
+    foreach my $k (sort keys %$data) {
         my $v = $data->{$k};
         $self->_SWITCH_refkind($v, {
           ARRAYREF => sub {
@@ -1899,7 +1975,7 @@ Which will change the above C<WHERE> to:
     WHERE event_date >= '2/13/99' AND event_date <= '4/24/03'
 
 The logic can also be changed locally by inserting
-a modifier in front of an arrayref :
+a modifier in front of an arrayref:
 
     @where = (-and => [event_date => {'>=', '2/13/99'},
                        event_date => {'<=', '4/24/03'} ]);
@@ -2003,7 +2079,7 @@ The parameter default in case of a single L</quote_char> character is the quote
 character itself.
 
 When opening-closing-style quoting is used (L</quote_char> is an arrayref)
-this parameter defaults to the B<closing (right)> L</quote_char>. Occurences
+this parameter defaults to the B<closing (right)> L</quote_char>. Occurrences
 of the B<opening (left)> L</quote_char> within the identifier are currently left
 untouched. The default for opening-closing-style quotes may change in future
 versions, thus you are B<strongly encouraged> to specify the escape character
@@ -2110,7 +2186,7 @@ L<insert|/insert($table, \@values || \%fieldvals, \%options)>.
 =head2 select($source, $fields, $where, $order)
 
 This returns a SQL SELECT statement and associated list of bind values, as
-specified by the arguments  :
+specified by the arguments:
 
 =over
 
@@ -2120,8 +2196,7 @@ Specification of the 'FROM' part of the statement.
 The argument can be either a plain scalar (interpreted as a table
 name, will be quoted), or an arrayref (interpreted as a list
 of table names, joined by commas, quoted), or a scalarref
-(literal table name, not quoted), or a ref to an arrayref
-(list of literal table names, joined by commas, not quoted).
+(literal SQL, not quoted).
 
 =item $fields
 
@@ -2150,11 +2225,24 @@ for details.
 =back
 
 
-=head2 delete($table, \%where)
+=head2 delete($table, \%where, \%options)
 
 This takes a table name and optional hashref L<WHERE clause|/WHERE CLAUSES>.
 It returns an SQL DELETE statement and list of bind values.
 
+The optional C<\%options> hash reference may contain additional
+options to generate the delete SQL. Currently supported options
+are:
+
+=over 4
+
+=item returning
+
+See the C<returning> option to
+L<insert|/insert($table, \@values || \%fieldvals, \%options)>.
+
+=back
+
 =head2 where(\%where, $order)
 
 This is used to generate just the WHERE clause. For example,
@@ -2223,7 +2311,7 @@ module:
 
 =back
 
-On failure returns C<undef>, on sucess returns a B<scalar> reference
+On failure returns C<undef>, on success returns a B<scalar> reference
 to the original supplied argument.
 
 =over
@@ -2281,7 +2369,7 @@ module:
 
 =back
 
-On failure returns C<undef>, on sucess returns an B<array> reference
+On failure returns C<undef>, on success returns an B<array> reference
 containing the unpacked version of the supplied literal SQL and bind values.
 
 =head1 WHERE CLAUSES
@@ -2462,7 +2550,7 @@ Here is a quick list of equivalencies, since there is some overlap:
 
 
 
-=head2 Special operators : IN, BETWEEN, etc.
+=head2 Special operators: IN, BETWEEN, etc.
 
 You can also use the hashref format to compare a list of fields using the
 C<IN> comparison operator, by specifying the list as an arrayref:
@@ -2481,8 +2569,8 @@ The reverse operator C<-not_in> generates SQL C<NOT IN> and is used in
 the same way.
 
 If the argument to C<-in> is an empty array, 'sqlfalse' is generated
-(by default : C<1=0>). Similarly, C<< -not_in => [] >> generates
-'sqltrue' (by default : C<1=1>).
+(by default: C<1=0>). Similarly, C<< -not_in => [] >> generates
+'sqltrue' (by default: C<1=1>).
 
 In addition to the array you can supply a chunk of literal sql or
 literal sql with bind:
@@ -2545,7 +2633,7 @@ Would give you:
 
 
 These are the two builtin "special operators"; but the
-list can be expanded : see section L</"SPECIAL OPERATORS"> below.
+list can be expanded: see section L</"SPECIAL OPERATORS"> below.
 
 =head2 Unary operators: bool
 
@@ -2609,7 +2697,7 @@ This data structure would create the following:
 
 
 Clauses in hashrefs or arrayrefs can be prefixed with an C<-and> or C<-or>
-to change the logic inside :
+to change the logic inside:
 
     my @where = (
          -and => [
@@ -2633,7 +2721,7 @@ That would yield:
 C<Important note>: when connecting several conditions, the C<-and->|C<-or>
 operator goes C<outside> of the nested structure; whereas when connecting
 several constraints on one column, the C<-and> operator goes
-C<inside> the arrayref. Here is an example combining both features :
+C<inside> the arrayref. Here is an example combining both features:
 
    my @where = (
      -and => [a => 1, b => 2],
@@ -2648,20 +2736,20 @@ yielding
             OR ( e LIKE ? AND e LIKE ? ) ) )
 
 This difference in syntax is unfortunate but must be preserved for
-historical reasons. So be careful : the two examples below would
+historical reasons. So be careful: the two examples below would
 seem algebraically equivalent, but they are not
 
   { col => [ -and =>
     { -like => 'foo%' },
     { -like => '%bar' },
   ] }
-  # yields : WHERE ( ( col LIKE ? AND col LIKE ? ) )
+  # yields: WHERE ( ( col LIKE ? AND col LIKE ? ) )
 
   [ -and =>
     { col => { -like => 'foo%' } },
     { col => { -like => '%bar' } },
   ]
-  # yields : WHERE ( ( col LIKE ? OR col LIKE ? ) )
+  # yields: WHERE ( ( col LIKE ? OR col LIKE ? ) )
 
 
 =head2 Literal SQL and value type operators
@@ -2775,7 +2863,7 @@ example will look like:
     )
 
 Literal SQL is especially useful for nesting parenthesized clauses in the
-main SQL query. Here is a first example :
+main SQL query. Here is a first example:
 
   my ($sub_stmt, @sub_bind) = ("SELECT c1 FROM t1 WHERE c2 < ? AND c3 LIKE ?",
                                100, "foo%");
@@ -2784,7 +2872,7 @@ main SQL query. Here is a first example :
     bar => \["IN ($sub_stmt)" => @sub_bind],
   );
 
-This yields :
+This yields:
 
   $stmt = "WHERE (foo = ? AND bar IN (SELECT c1 FROM t1
                                              WHERE c2 < ? AND c3 LIKE ?))";
@@ -2805,7 +2893,7 @@ to C<select()> :
 
 In the examples above, the subquery was used as an operator on a column;
 but the same principle also applies for a clause within the main C<%where>
-hash, like an EXISTS subquery :
+hash, like an EXISTS subquery:
 
   my ($sub_stmt, @sub_bind)
      = $sql->select("t1", "*", {c1 => 1, c2 => \"> t0.c0"});
@@ -2822,7 +2910,7 @@ which yields
 
 
 Observe that the condition on C<c2> in the subquery refers to
-column C<t0.c0> of the main query : this is I<not> a bind
+column C<t0.c0> of the main query: this is I<not> a bind
 value, so we have to express it through a scalar ref.
 Writing C<< c2 => {">" => "t0.c0"} >> would have generated
 C<< c2 > ? >> with bind value C<"t0.c0"> ... not exactly
@@ -2957,7 +3045,7 @@ forms. Examples:
 
 A "special operator" is a SQL syntactic clause that can be
 applied to a field, instead of a usual binary operator.
-For example :
+For example:
 
    WHERE field IN (?, ?, ?)
    WHERE field BETWEEN ? AND ?
@@ -2986,7 +3074,7 @@ the expected return is C<< ($sql, @bind) >>.
 When supplied with a method name, it is simply called on the
 L<SQL::Abstract> object as:
 
- $self->$method_name ($field, $op, $arg)
+ $self->$method_name($field, $op, $arg)
 
  Where:
 
@@ -3062,7 +3150,7 @@ the expected return is C<< $sql >>.
 When supplied with a method name, it is simply called on the
 L<SQL::Abstract> object as:
 
- $self->$method_name ($op, $arg)
+ $self->$method_name($op, $arg)
 
  Where:
 
@@ -3176,7 +3264,7 @@ to clarify the semantics. Hence, client code that was relying
 on some dark areas of C<SQL::Abstract> v1.*
 B<might behave differently> in v1.50.
 
-The main changes are :
+The main changes are:
 
 =over
 
@@ -3198,7 +3286,7 @@ optional support for L<array datatypes|/"Inserting and Updating Arrays">
 
 =item *
 
-defensive programming : check arguments
+defensive programming: check arguments
 
 =item *
 
@@ -3269,4 +3357,3 @@ terms as perl itself (either the GNU General Public License or
 the Artistic License)
 
 =cut
-