Make it clearer in examples that bool takes expressions

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

diff --git a/lib/SQL/Abstract.pm b/lib/SQL/Abstract.pm
index 3940881..d017b85 100644 (file)
--- a/lib/SQL/Abstract.pm
+++ b/lib/SQL/Abstract.pm
@@ -86,7 +86,7 @@ sub new {
   # default comparison is "=", but can be overridden
   $opt{cmp} ||= '=';
 
-  # try to recognize which are the 'equality' and 'unequality' ops
+  # try to recognize which are the 'equality' and 'inequality' ops
   # (temporary quickfix, should go through a more seasoned API)
   $opt{equality_op}   = qr/^(\Q$opt{cmp}\E|is|(is\s+)?like)$/i;
   $opt{inequality_op} = qr/^(!=|<>|(is\s+)?not(\s+like)?)$/i;
@@ -104,7 +104,7 @@ sub new {
   $opt{unary_ops} ||= [];
   push @{$opt{unary_ops}}, @BUILTIN_UNARY_OPS;
 
-  # rudimentary saniy-check for user supplied bits treated as functions/operators
+  # rudimentary sanity-check for user supplied bits treated as functions/operators
   # If a purported  function matches this regular expression, an exception is thrown.
   # Literal SQL is *NOT* subject to this check, only functions (and column names
   # when quoting is not in effect)
@@ -961,6 +961,8 @@ sub _where_field_BETWEEN {
   $placeholder = $self->_convert('?');
   $op               = $self->_sqlcase($op);
 
+  my $invalid_args = "Operator '$op' requires either an arrayref with two defined values or expressions, or a single literal scalarref/arrayref-ref";
+
   my ($clause, @bind) = $self->_SWITCH_refkind($vals, {
     ARRAYREFREF => sub {
       my ($s, @b) = @$$vals;
@@ -971,8 +973,7 @@ sub _where_field_BETWEEN {
       return $$vals;
     },
     ARRAYREF => sub {
-      puke "special op 'between' accepts an arrayref with exactly two values"
-        if @$vals != 2;
+      puke $invalid_args if @$vals != 2;
 
       my (@all_sql, @all_bind);
       foreach my $val (@$vals) {
@@ -994,7 +995,10 @@ sub _where_field_BETWEEN {
                if (@rest or $func !~ /^ \- (.+)/x);
              local $self->{_nested_func_lhs} = $k;
              $self->_where_unary_op ($1 => $arg);
-           }
+           },
+           FALLBACK => sub {
+             puke $invalid_args,
+           },
         });
         push @all_sql, $sql;
         push @all_bind, @bind;
@@ -1006,7 +1010,7 @@ sub _where_field_BETWEEN {
       );
     },
     FALLBACK => sub {
-      puke "special op 'between' accepts an arrayref with two values, or a single literal scalarref/arrayref-ref";
+      puke $invalid_args,
     },
   });
 
@@ -1051,7 +1055,12 @@ sub _where_field_IN {
               $self->_where_unary_op ($1 => $arg);
             },
             UNDEF => sub {
-              return $self->_sqlcase('null');
+              puke(
+                'SQL::Abstract before v1.75 used to generate incorrect SQL when the '
+              . "-$op operator was given an undef-containing list: !!!AUDIT YOUR CODE "
+              . 'AND DATA!!! (the upcoming Data::Query-based version of SQL::Abstract '
+              . 'will emit the logically correct SQL instead of raising this exception)'
+              );
             },
           });
           push @all_sql, $sql;
@@ -1084,8 +1093,12 @@ sub _where_field_IN {
       return ("$label $op ( $sql )", @bind);
     },
 
+    UNDEF => sub {
+      puke "Argument passed to the '$op' operator can not be undefined";
+    },
+
     FALLBACK => sub {
-      puke "special op 'in' requires an arrayref (or scalarref/arrayref-ref)";
+      puke "special op $op requires an arrayref (or scalarref/arrayref-ref)";
     },
   });
 
@@ -1699,7 +1712,7 @@ C<cmp> to C<like> you would get SQL such as:
 
     WHERE name like 'nwiger' AND email like 'nate@wiger.org'
 
-You can also override the comparsion on an individual basis - see
+You can also override the comparison on an individual basis - see
 the huge section on L</"WHERE CLAUSES"> at the bottom.
 
 =item sqltrue, sqlfalse
@@ -2231,7 +2244,8 @@ would generate:
     )";
     @bind = ('2000');
 
-
+Finally, if the argument to C<-in> is not a reference, it will be
+treated as a single-element array.
 
 Another pair of operators is C<-between> and C<-not_between>,
 used with an arrayref of two values:
@@ -2296,15 +2310,19 @@ then you should use the and/or operators:-
     my %where  = (
         -and           => [
             -bool      => 'one',
-            -bool      => 'two',
-            -bool      => 'three',
-            -not_bool  => 'four',
+            -not_bool  => { two=> { -rlike => 'bar' } },
+            -not_bool  => { three => [ { '=', 2 }, { '>', 5 } ] },
         ],
     );
 
 Would give you:
 
-    WHERE one AND two AND three AND NOT four
+    WHERE
+      one
+        AND
+      (NOT two RLIKE ?)
+        AND
+      (NOT ( three = ? OR three > ? ))
 
 
 =head2 Nested conditions, -and/-or prefixes
@@ -2431,7 +2449,7 @@ Note that if you were to simply say:
         array => [1, 2, 3]
     );
 
-the result would porbably be not what you wanted:
+the result would probably not be what you wanted:
 
     $stmt = 'WHERE array = ? OR array = ? OR array = ?';
     @bind = (1, 2, 3);