Undocument -nest with extreme prejudice

-nest is a wart that never served any reasonable purpose. While
DBIC is outright deprecating it, SQLA is simply undocumenting it,
committing to keep all tests intact (but not committing to
reimplement -nest in the Data::Query adapter).

diff --git a/Changes b/Changes
index ff220c6..be48dd2 100644 (file)
--- a/Changes
+++ b/Changes
@@ -4,6 +4,8 @@ Revision history for SQL::Abstract
     - Fix parsing of foo.* in SQLA::Tree
     - Fix bindtype fail when using -between with arrayrefref literals
     - Add handling for NULL for -in
+    - The -nest operator has entered semi-deprecated status and has been
+      undocumented. Please do not use it in new code
 
 revision 1.71  2010-11-09
 ----------------------------

diff --git a/lib/SQL/Abstract.pm b/lib/SQL/Abstract.pm
index 238d869..4802d4c 100644 (file)
--- a/lib/SQL/Abstract.pm
+++ b/lib/SQL/Abstract.pm
@@ -572,15 +572,23 @@ sub _where_op_ANDOR {
     },
 
     SCALARREF  => sub {
-      puke "-$op => \\\$scalar not supported, use -nest => ...";
+      puke "-$op => \\\$scalar makes little sense, use " .
+        ($op =~ /^or/i 
+          ? '[ \$scalar, \%rest_of_conditions ] instead'
+          : '-and => [ \$scalar, \%rest_of_conditions ] instead'
+        );
     },
 
     ARRAYREFREF => sub {
-      puke "-$op => \\[..] not supported, use -nest => ...";
+      puke "-$op => \\[...] makes little sense, use " .
+        ($op =~ /^or/i 
+          ? '[ \[...], \%rest_of_conditions ] instead'
+          : '-and => [ \[...], \%rest_of_conditions ] instead'
+        );
     },
 
     SCALAR => sub { # permissively interpreted as SQL
-      puke "-$op => 'scalar' not supported, use -nest => \\'scalar'";
+      puke "-$op => \$value makes little sense, use -bool => \$value instead";
     },
 
     UNDEF => sub {
@@ -2227,41 +2235,25 @@ This data structure would create the following:
     @bind = ('nwiger', 'pending', 'dispatched', 'robot', 'unassigned');
 
 
-There is also a special C<-nest>
-operator which adds an additional set of parens, to create a subquery.
-For example, to get something like this:
-
-    $stmt = "WHERE user = ? AND ( workhrs > ? OR geo = ? )";
-    @bind = ('nwiger', '20', 'ASIA');
-
-You would do:
-
-    my %where = (
-         user => 'nwiger',
-        -nest => [ workhrs => {'>', 20}, geo => 'ASIA' ],
-    );
-
-
-Finally, clauses in hashrefs or arrayrefs can be
-prefixed with an C<-and> or C<-or> to change the logic
-inside :
+Clauses in hashrefs or arrayrefs can be prefixed with an C<-and> or C<-or>
+to change the logic inside :
 
     my @where = (
          -and => [
             user => 'nwiger',
-            -nest => [
-                -and => [workhrs => {'>', 20}, geo => 'ASIA' ],
-                -and => [workhrs => {'<', 50}, geo => 'EURO' ]
+            [
+                -and => [ workhrs => {'>', 20}, geo => 'ASIA' ],
+                -or => { workhrs => {'<', 50}, geo => 'EURO' },
             ],
         ],
     );
 
 That would yield:
 
-    WHERE ( user = ? AND
-          ( ( workhrs > ? AND geo = ? )
-         OR ( workhrs < ? AND geo = ? ) ) )
-
+    WHERE ( user = ? AND (
+               ( workhrs > ? AND geo = ? )
+            OR ( workhrs < ? OR geo = ? )
+          ) )
 
 =head2 Algebraic inconsistency, for historical reasons
 
@@ -2413,10 +2405,10 @@ hash, like an EXISTS subquery :
 
   my ($sub_stmt, @sub_bind)
      = $sql->select("t1", "*", {c1 => 1, c2 => \"> t0.c0"});
-  my %where = (
+  my %where = ( -and => [
     foo   => 1234,
-    -nest => \["EXISTS ($sub_stmt)" => @sub_bind],
-  );
+    \["EXISTS ($sub_stmt)" => @sub_bind],
+  ]);
 
 which yields
 
@@ -2432,15 +2424,6 @@ Writing C<< c2 => {">" => "t0.c0"} >> would have generated
 C<< c2 > ? >> with bind value C<"t0.c0"> ... not exactly
 what we wanted here.
 
-Another use of the subquery technique is when some SQL clauses need
-parentheses, as it often occurs with some proprietary SQL extensions
-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/]
-  );
-
 Finally, here is an example where a subquery is used
 for expressing unary negation:
 
@@ -2449,7 +2432,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],
+        \["NOT ($sub_stmt)" => @sub_bind],
     );
 
 This yields
@@ -2795,7 +2778,7 @@ 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, 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)
     Oliver Charles (support for "RETURNING" after "INSERT")

diff --git a/lib/SQL/Abstract/Test.pm b/lib/SQL/Abstract/Test.pm
index 318b6ef..2485006 100644 (file)
--- a/lib/SQL/Abstract/Test.pm
+++ b/lib/SQL/Abstract/Test.pm
@@ -307,7 +307,8 @@ If true, SQL comparisons will be case-sensitive. Default is false;
 =head2 $parenthesis_significant
 
 If true, SQL comparison will preserve and report difference in nested
-parenthesis. Useful for testing the C<-nest> modifier. Defaults to false;
+parenthesis. Useful while testing C<IN (( x ))> vs C<IN ( x )>.
+Defaults to false;
 
 =head2 $sql_differ
 

diff --git a/t/01generate.t b/t/01generate.t
index 5855f80..90e94f8 100644 (file)
--- a/t/01generate.t
+++ b/t/01generate.t
@@ -10,6 +10,15 @@ use SQL::Abstract::Test import => ['is_same_sql_bind'];
 
 use SQL::Abstract;
 
+#### WARNING ####
+#
+# -nest has been undocumented on purpose, but is still supported for the
+# foreseable future. Do not rip out the -nest tests before speaking to
+# someone on the DBIC mailing list or in irc.perl.org#dbix-class
+#
+#################
+
+
 my @tests = (
       {
               func   => 'select',

diff --git a/t/02where.t b/t/02where.t
index 5fea555..1b97d7c 100644 (file)
--- a/t/02where.t
+++ b/t/02where.t
@@ -201,6 +201,24 @@ my @handle_tests = (
         stmt => " WHERE ( (bar > ? AND bar < ?) AND foo IN (?, ?) )",
         bind => [44, 55, 22, 33],
     },
+
+    {
+        where => {
+          -and => [
+            user => 'nwiger',
+            [
+              -and => [ workhrs => {'>', 20}, geo => 'ASIA' ],
+              -or => { workhrs => {'<', 50}, geo => 'EURO' },
+            ],
+          ],
+        },
+        stmt => "WHERE ( user = ? AND (
+               ( workhrs > ? AND geo = ? )
+            OR ( geo = ? OR workhrs < ? )
+          ) )",
+        bind => [qw/nwiger 20 ASIA EURO 50/],
+    },
+
    {
        where => { -and => [{}, { 'me.id' => '1'}] },
        stmt => " WHERE ( ( me.id = ? ) )",

diff --git a/t/04modifiers.t b/t/04modifiers.t
index 355ef67..87ddbfc 100644 (file)
--- a/t/04modifiers.t
+++ b/t/04modifiers.t
@@ -10,6 +10,14 @@ use Data::Dumper;
 use Storable qw/dclone/;
 use SQL::Abstract;
 
+#### WARNING ####
+#
+# -nest has been undocumented on purpose, but is still supported for the
+# foreseable future. Do not rip out the -nest tests before speaking to
+# someone on the DBIC mailing list or in irc.perl.org#dbix-class
+#
+#################
+
 =begin
 Test -and -or and -nest modifiers, assuming the following:
 

diff --git a/t/07subqueries.t b/t/07subqueries.t
index f14738a..df90bdf 100644 (file)
--- a/t/07subqueries.t
+++ b/t/07subqueries.t
@@ -8,6 +8,15 @@ use SQL::Abstract::Test import => ['is_same_sql_bind'];
 
 use SQL::Abstract;
 
+#### WARNING ####
+#
+# -nest has been undocumented on purpose, but is still supported for the
+# foreseable future. Do not rip out the -nest tests before speaking to
+# someone on the DBIC mailing list or in irc.perl.org#dbix-class
+#
+#################
+
+
 my $sql = SQL::Abstract->new;
 
 my (@tests, $sub_stmt, @sub_bind, $where);