Deprecate -nest in favor of -paren

[dbsrgits/SQL-Abstract.git] / lib / SQL / Abstract.pm

diff --git a/lib/SQL/Abstract.pm b/lib/SQL/Abstract.pm
index 57a77ba..a569708 100644 (file)
--- a/lib/SQL/Abstract.pm
+++ b/lib/SQL/Abstract.pm
@@ -15,7 +15,7 @@ use Scalar::Util qw/blessed/;
 # GLOBALS
 #======================================================================
 
-our $VERSION  = '1.51';
+our $VERSION  = '1.53';
 
 # This would confuse some packagers
 #$VERSION      = eval $VERSION; # numify for warning-free dev releases
@@ -422,7 +422,6 @@ sub _where_HASHREF {
   my ($self, $where) = @_;
   my (@sql_clauses, @all_bind);
 
-  # LDNOTE : don't really know why we need to sort keys
   for my $k (sort keys %$where) { 
     my $v = $where->{$k};
 
@@ -444,49 +443,54 @@ sub _where_HASHREF {
 sub _where_op_in_hash {
   my ($self, $op_str, $v) = @_; 
 
-  $op_str =~ /^ (AND|OR|NEST) ( \_? \d* ) $/xi
+  $op_str =~ /^ (AND|OR|PAREN|NEST) ( \_? \d* ) $/xi
     or puke "unknown operator: -$op_str";
 
   my $op = uc($1); # uppercase, remove trailing digits
   if ($2) {
-    belch 'Use of [and|or|nest]_N modifiers is deprecated and will be removed in SQLA v2.0. '
+    belch 'Use of op_N modifiers is deprecated and will be removed in SQLA v2.0. '
           . "You probably wanted ...-and => [ $op_str => COND1, $op_str => COND2 ... ]";
   }
 
+  if ($op eq 'NEST') {
+    belch 'The -nest modifier is deprecated in favor of -paren and will be removed in SQLA v2.0';
+    $op = 'PAREN';
+  }
+
   $self->_debug("OP(-$op) within hashref, recursing...");
 
   $self->_SWITCH_refkind($v, {
 
     ARRAYREF => sub {
-      return $self->_where_ARRAYREF($v, $op eq 'NEST' ? '' : $op);
+      return $self->_where_ARRAYREF($v, $op eq 'PAREN' ? '' : $op);
     },
 
     HASHREF => sub {
       if ($op eq 'OR') {
-        return $self->_where_ARRAYREF([%$v], 'OR');
+        return $self->_where_ARRAYREF([ map { $_ => $v->{$_} } (sort keys %$v) ], 'OR');
       } 
-      else {                  # NEST | AND
+      else {                  # PAREN | AND
         return $self->_where_HASHREF($v);
       }
     },
 
     SCALARREF  => sub {         # literal SQL
-      $op eq 'NEST' 
-        or puke "-$op => \\\$scalar not supported, use -nest => ...";
+      $op eq 'PAREN' 
+        or puke "-$op => \\\$scalar not supported, use -paren => ...";
       return ($$v); 
     },
 
     ARRAYREFREF => sub {        # literal SQL
-      $op eq 'NEST' 
-        or puke "-$op => \\[..] not supported, use -nest => ...";
+      $op eq 'PAREN' 
+        or puke "-$op => \\[..] not supported, use -paren => ...";
       return @{${$v}};
     },
 
     SCALAR => sub { # permissively interpreted as SQL
-      $op eq 'NEST' 
-        or puke "-$op => 'scalar' not supported, use -nest => \\'scalar'";
-      belch "literal SQL should be -nest => \\'scalar' "
-          . "instead of -nest => 'scalar' ";
+      $op eq 'PAREN' 
+        or puke "-$op => 'scalar' not supported, use -paren => \\'scalar'";
+      belch "literal SQL should be -paren => \\'scalar' "
+          . "instead of -paren => 'scalar' ";
       return ($v); 
     },
 
@@ -1852,7 +1856,7 @@ This data structure would create the following:
     @bind = ('nwiger', 'pending', 'dispatched', 'robot', 'unassigned');
 
 
-There is also a special C<-nest>
+There is also a special C<-paren>
 operator which adds an additional set of parens, to create a subquery.
 For example, to get something like this:
 
@@ -1863,7 +1867,7 @@ You would do:
 
     my %where = (
          user => 'nwiger',
-        -nest => [ workhrs => {'>', 20}, geo => 'ASIA' ],
+        -paren => [ workhrs => {'>', 20}, geo => 'ASIA' ],
     );
 
 
@@ -1874,7 +1878,7 @@ inside :
     my @where = (
          -and => [
             user => 'nwiger',
-            -nest => [
+            -paren => [
                 -and => [workhrs => {'>', 20}, geo => 'ASIA' ],
                 -and => [workhrs => {'<', 50}, geo => 'EURO' ]
             ],
@@ -2027,7 +2031,7 @@ hash, like an EXISTS subquery :
      = $sql->select("t1", "*", {c1 => 1, c2 => \"> t0.c0"});
   my %where = (
     foo   => 1234,
-    -nest => \["EXISTS ($sub_stmt)" => @sub_bind],
+    -paren => \["EXISTS ($sub_stmt)" => @sub_bind],
   );
 
 which yields
@@ -2050,7 +2054,7 @@ like for example fulltext expressions, geospatial expressions,
 NATIVE clauses, etc. Here is an example of a fulltext query in MySQL :
 
   my %where = (
-    -nest => \["MATCH (col1, col2) AGAINST (?)" => qw/apples/]
+    -paren => \["MATCH (col1, col2) AGAINST (?)" => qw/apples/]
   );
 
 Finally, here is an example where a subquery is used
@@ -2061,7 +2065,7 @@ for expressing unary negation:
   $sub_stmt =~ s/^ where //i; # don't want "WHERE" in the subclause
   my %where = (
         lname  => {like => '%son%'},
-        -nest  => \["NOT ($sub_stmt)" => @sub_bind],
+        -paren  => \["NOT ($sub_stmt)" => @sub_bind],
     );
 
 This yields
@@ -2319,8 +2323,9 @@ so I have no idea who they are! But the people I do know are:
     Mike Fragassi (enhancements to "BETWEEN" and "LIKE")
     Dan Kubb (support for "quote_char" and "name_sep")
     Guillermo Roditi (patch to cleanup "IN" and "BETWEEN", fix and tests for _order_by)
-    Laurent Dami (internal refactoring, multiple -nest, extensible list of special operators, literal SQL)
+    Laurent Dami (internal refactoring, multiple -paren, extensible list of special operators, literal SQL)
     Norbert Buchmuller (support for literal SQL in hashpair, misc. fixes & tests)
+    Peter Rabbitson (rewrite of SQLA::Test, misc. fixes & tests)
 
 Thanks!
 
@@ -2339,6 +2344,8 @@ While not an official support venue, C<DBIx::Class> makes heavy use of
 C<SQL::Abstract>, and as such list members there are very familiar with
 how to create queries.
 
+=head1 LICENSE
+
 This module is free software; you may copy this under the terms of
 the GNU General Public License, or the Artistic License, copies of
 which should have accompanied your Perl kit.