Cleaning up docs as ribasushi suggested. Made it clear that literal sql

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

diff --git a/lib/SQL/Abstract.pm b/lib/SQL/Abstract.pm
index e5d07d4..e82242c 100644 (file)
--- a/lib/SQL/Abstract.pm
+++ b/lib/SQL/Abstract.pm
@@ -5,9 +5,9 @@ package SQL::Abstract; # see doc at end of file
 # the test / diffusion / acceptance phase; those are marked with flag
 # 'LDNOTE' (note by laurent.dami AT free.fr)
 
-use Carp;
 use strict;
 use warnings;
+use Carp ();
 use List::Util ();
 use Scalar::Util ();
 
@@ -50,12 +50,12 @@ sub _debug {
 
 sub belch (@) {
   my($func) = (caller(1))[3];
-  carp "[$func] Warning: ", @_;
+  Carp::carp "[$func] Warning: ", @_;
 }
 
 sub puke (@) {
   my($func) = (caller(1))[3];
-  croak "[$func] Fatal: ", @_;
+  Carp::croak "[$func] Fatal: ", @_;
 }
 
 
@@ -556,7 +556,7 @@ sub _where_unary_op {
     }
   }
 
-  $self->debug("Generic unary OP: $op - recursing as function");
+  $self->_debug("Generic unary OP: $op - recursing as function");
 
   $self->_assert_pass_injection_guard($op);
 
@@ -2029,6 +2029,13 @@ becomes:
     $stmt = "WHERE user = ? AND status IS NULL";
     @bind = ('nwiger');
 
+To test if a column IS NOT NULL:
+
+    my %where  = (
+        user   => 'nwiger',
+        status => { '!=', undef },
+    );
+    
 =head2 Specific comparison operators
 
 If you want to specify a different type of operator for your comparison,
@@ -2075,13 +2082,13 @@ To get an OR instead, you can combine it with the arrayref idea:
 
     my %where => (
          user => 'nwiger',
-         priority => [ {'=', 2}, {'!=', 1} ]
+         priority => [ { '=', 2 }, { '>', 5 } ]
     );
 
 Which would generate:
 
-    $stmt = "WHERE user = ? AND priority = ? OR priority != ?";
-    @bind = ('nwiger', '2', '1');
+    $stmt = "WHERE ( priority = ? OR priority > ? ) AND user = ?";
+    @bind = ('2', '5', 'nwiger');
 
 If you want to include literal SQL (with or without bind values), just use a
 scalar reference or array reference as the value:
@@ -2331,10 +2338,26 @@ seem algebraically equivalent, but they are not
 
 =head2 Literal SQL
 
-Finally, sometimes only literal SQL will do. If you want to include
-literal SQL verbatim, you can specify it as a scalar reference, namely:
+Finally, sometimes only literal SQL will do.
+To include literal SQL verbatim, you specify it as a scalar reference.
+Consider this only as a last resort. Usually there is a better way.
+
+Literal SQL is the only way to compare 2 columns to one another:
 
-    my $inn = 'is Not Null';
+    my %where = (
+        priority => { '<', 2 },
+        requestor => \'= submittor'
+    );
+
+which creates:
+
+    $stmt = "WHERE priority < ? AND requestor = submitter";
+    @bind = ('2');
+
+
+There is a nicer way to test for NULL, but just for the sake of example:
+
+    my $inn = 'IS NOT NULL';
     my %where = (
         priority => { '<', 2 },
         requestor => \$inn
@@ -2357,9 +2380,7 @@ with this:
     );
 
 
-TMTOWTDI
-
-Conditions on boolean columns can be expressed in the same way, passing
+Conditions on boolean columns can be expressed by passing
 a reference to an empty string, however using liternal SQL in this way
 is deprecated - the preferred method is to use the boolean operators -
 see L</"Unary operators: bool"> :
@@ -2374,18 +2395,6 @@ which yields
     $stmt = "WHERE priority < ? AND is_ready";
     @bind = ('2');
 
-Literal SQL is also the only way to compare 2 columns to one another:
-
-    my %where = (
-        priority => { '<', 2 },
-        requestor => \'= submittor'
-    );
-
-which creates:
-
-    $stmt = "WHERE priority < ? AND requestor = submitter";
-    @bind = ('2');
-
 =head2 Literal SQL with placeholders and bind values (subqueries)
 
 If the literal SQL to be inserted has placeholders and bind values,