From: Naveed Massjouni <naveedm9@gmail.com>
Date: Fri, 22 Apr 2011 22:08:21 +0000 (-0400)
Subject: Cleaning up docs as ribasushi suggested. Made it clear that literal sql
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=e9614080e661336151dd9989798c5aa7fd3f8209;p=scpubgit%2FQ-Branch.git

Cleaning up docs as ribasushi suggested. Made it clear that literal sql
should be used as a last resort.  Provided an example for testing IS NOT NULL.
---

diff --git a/lib/SQL/Abstract.pm b/lib/SQL/Abstract.pm
index 03ffca2..e82242c 100644
--- a/lib/SQL/Abstract.pm
+++ b/lib/SQL/Abstract.pm
@@ -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,
@@ -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,