sequel 3.12.1 → 3.13.0

data/lib/sequel/sql.rb

@@ -1,7 +1,7 @@
 module Sequel
   if RUBY_VERSION < '1.9.0'
-    # If on Ruby 1.8, create a Sequel::BasicObject class that is similar to the
-    # the Ruby 1.9 BasicObject class.  This is used in a few places where proxy
+    # If on Ruby 1.8, create a <tt>Sequel::BasicObject</tt> class that is similar to the
+    # the Ruby 1.9 +BasicObject+ class.  This is used in a few places where proxy
     # objects are needed that respond to any method call.
     class BasicObject
       # The instance methods to not remove from the class when removing
@@ -10,26 +10,26 @@ module Sequel
 
       # Remove all but the most basic instance methods from the class.  A separate
       # method so that it can be called again if necessary if you load libraries
-      # after Sequel that add instance methods to Object.
+      # after Sequel that add instance methods to +Object+.
       def self.remove_methods!
         ((private_instance_methods + instance_methods) - KEEP_METHODS).each{|m| undef_method(m)}
       end
       remove_methods!
     end
   else
-    # If on 1.9, create a Sequel::BasicObject class that is just like the
-    # default BasicObject class, except that missing constants are resolved in
-    # Object.  This allows the virtual row support to work with classes
+    # If on 1.9, create a <tt>Sequel::BasicObject</tt> class that is just like the
+    # default +BasicObject+ class, except that missing constants are resolved in
+    # +Object+.  This allows the virtual row support to work with classes
     # without prefixing them with ::, such as:
     #
     #   DB[:bonds].filter{maturity_date > Time.now}
     class BasicObject < ::BasicObject
-      # Lookup missing constants in ::Object
+      # Lookup missing constants in <tt>::Object</tt>
       def self.const_missing(name)
         ::Object.const_get(name)
       end
 
-      # No-op method on ruby 1.9, which has a real BasicObject class.
+      # No-op method on ruby 1.9, which has a real +BasicObject+ class.
       def self.remove_methods!
       end
     end
@@ -45,17 +45,22 @@ module Sequel
 
     ### Parent Classes ###
 
-    # Classes/Modules aren't an alphabetical order due to the fact that
+    # Classes/Modules aren't in alphabetical order due to the fact that
     # some reference constants defined in others at load time.
 
-    # Base class for all SQL fragments
+    # Base class for all SQL expression objects.
     class Expression
-      # all instance variables declared to be readers are to be used for comparison.
+      # Expression objects are assumed to be value objects, where their
+      # attribute values can't change after assignment.  In order to make
+      # it easy to define equality and hash methods, subclass
+      # instances assume that the only values that affect the results of
+      # such methods are the values of the object's attributes.
       def self.attr_reader(*args)
         super
         comparison_attrs.concat args
       end
 
+      # All attributes used for equality and hash methods.
       def self.comparison_attrs
         @comparison_attrs ||= self == Expression ? [] : superclass.comparison_attrs.clone
       end
@@ -68,7 +73,7 @@ module Sequel
       end
       private_class_method :to_s_method
 
-      # Alias of eql?
+      # Alias of <tt>eql?</tt>
       def ==(other)
         eql?(other)
       end
@@ -76,7 +81,7 @@ module Sequel
       # Returns true if the receiver is the same expression as the
       # the +other+ expression.
       def eql?(other)
-        other.is_a?(self.class) && !self.class.comparison_attrs.find {|a| send(a) != other.send(a)}
+        other.is_a?(self.class) && !self.class.comparison_attrs.find{|a| send(a) != other.send(a)}
       end
 
       # Make sure that the hash value is the same if the attributes are the same.
@@ -84,13 +89,18 @@ module Sequel
         ([self.class] + self.class.comparison_attrs.map{|x| send(x)}).hash
       end
 
-      # Returns self, because SQL::Expression already acts like
-      # LiteralString.
+      # Show the class name and instance variables for the object, necessary
+      # for correct operation on ruby 1.9.2.
+      def inspect
+        "#<#{self.class} #{instance_variables.map{|iv| "#{iv}=>#{instance_variable_get(iv).inspect}"}.join(', ')}>"
+      end
+
+      # Returns +self+, because <tt>SQL::Expression</tt> already acts like +LiteralString+.
       def lit
         self
       end
       
-      # Alias of to_s
+      # Alias of +to_s+
       def sql_literal(ds)
         to_s(ds)
       end
@@ -98,11 +108,10 @@ module Sequel
 
     # Represents a complex SQL expression, with a given operator and one
     # or more attributes (which may also be ComplexExpressions, forming
-    # a tree).  This class is the backbone of the blockless filter support in
-    # Sequel.
+    # a tree).  This class is the backbone of Sequel's ruby expression DSL.
     #
     # This is an abstract class that is not that useful by itself.  The
-    # subclasses BooleanExpression, NumericExpression, and StringExpression
+    # subclasses +BooleanExpression+, +NumericExpression+, and +StringExpression+
     # define the behavior of the DSL via operators.
     class ComplexExpression < Expression
       # A hash of the opposite for each operator symbol, used for inverting
@@ -114,30 +123,33 @@ module Sequel
         :'!~*' => :'~*', :NOT => :NOOP, :NOOP => :NOT, :ILIKE => :'NOT ILIKE',
         :'NOT ILIKE'=>:ILIKE}
 
-      # Standard Mathematical Operators used in NumericMethods
+      # Standard mathematical operators used in +NumericMethods+
       MATHEMATICAL_OPERATORS = [:+, :-, :/, :*]
 
-      # Bitwise Mathematical Operators used in NumericMethods
+      # Bitwise mathematical operators used in +NumericMethods+
       BITWISE_OPERATORS = [:&, :|, :^, :<<, :>>]
 
-      # Inequality Operators used in InequalityMethods
+      # Inequality operators used in +InequalityMethods+
       INEQUALITY_OPERATORS = [:<, :>, :<=, :>=]
 
-      # Hash of ruby operator symbols to SQL operators, used in BooleanMethods
+      # Hash of ruby operator symbols to SQL operators, used in +BooleanMethods+
       BOOLEAN_OPERATOR_METHODS = {:& => :AND, :| =>:OR}
 
+      # Operators that use IN/NOT IN for inclusion/exclusion
+      IN_OPERATORS = [:IN, :'NOT IN']
+
       # Operators that use IS, used for special casing to override literal true/false values
       IS_OPERATORS = [:IS, :'IS NOT']
 
       # Operator symbols that take exactly two arguments
       TWO_ARITY_OPERATORS = [:'=', :'!=', :LIKE, :'NOT LIKE', \
-        :~, :'!~', :'~*', :'!~*', :IN, :'NOT IN', :ILIKE, :'NOT ILIKE'] + \
-        INEQUALITY_OPERATORS + BITWISE_OPERATORS + IS_OPERATORS 
+        :~, :'!~', :'~*', :'!~*', :ILIKE, :'NOT ILIKE'] + \
+        INEQUALITY_OPERATORS + BITWISE_OPERATORS + IS_OPERATORS + IN_OPERATORS
 
       # Operator symbols that take one or more arguments
       N_ARITY_OPERATORS = [:AND, :OR, :'||'] + MATHEMATICAL_OPERATORS
 
-      # Operator symbols that take one argument
+      # Operator symbols that take only a single argument
       ONE_ARITY_OPERATORS = [:NOT, :NOOP, :'B~']
 
       # An array of args for this object
@@ -147,11 +159,13 @@ module Sequel
       attr_reader :op
       
       # Set the operator symbol and arguments for this object to the ones given.
-      # Convert all args that are hashes or arrays with all two pairs to BooleanExpressions.
-      # Raise an error if the operator doesn't allow boolean input and a boolean argument is given.
-      # Raise an error if the wrong number of arguments for a given operator is used.
+      # Convert all args that are hashes or arrays of two element arrays to +BooleanExpressions+,
+      # other than the second arg for an IN/NOT IN operator.
+      # Raise an +Error+ if the operator doesn't allow boolean input and a boolean argument is given.
+      # Raise an +Error+ if the wrong number of arguments for a given operator is used.
       def initialize(op, *args)
-        args.map!{|a| Sequel.condition_specifier?(a) ? SQL::BooleanExpression.from_value_pairs(a) : a}
+        orig_args = args
+        args = args.map{|a| Sequel.condition_specifier?(a) ? SQL::BooleanExpression.from_value_pairs(a) : a}
         case op
         when *N_ARITY_OPERATORS
           raise(Error, "The #{op} operator requires at least 1 argument") unless args.length >= 1
@@ -160,6 +174,10 @@ module Sequel
           old_args.each{|a| a.is_a?(self.class) && a.op == op ? args.concat(a.args) : args.push(a)}
         when *TWO_ARITY_OPERATORS
           raise(Error, "The #{op} operator requires precisely 2 arguments") unless args.length == 2
+          # With IN/NOT IN, even if the second argument is an array of two element arrays,
+          # don't convert it into a boolean expression, since it's definitely being used
+          # as a value list.
+          args[1] = orig_args[1] if IN_OPERATORS.include?(op)
         when *ONE_ARITY_OPERATORS
           raise(Error, "The #{op} operator requires a single argument") unless args.length == 1
         else
@@ -173,23 +191,32 @@ module Sequel
     end
 
     # The base class for expressions that can be used in multiple places in
-    # the SQL query.  
+    # an SQL query.  
     class GenericExpression < Expression
     end
     
     ### Modules ###
 
-    # Methods that create aliased identifiers
+    # Includes an +as+ method that creates an SQL alias.
     module AliasMethods
-      # Create an SQL column alias of the receiving column or expression to the given alias.
+      # Create an SQL alias (+AliasedExpression+) of the receiving column or expression to the given alias.
+      #
+      #   :column.as(:alias) # "column" AS "alias"
       def as(aliaz)
         AliasedExpression.new(self, aliaz)
       end
     end
 
     # This defines the bitwise methods: &, |, ^, ~, <<, and >>.  Because these
-    # methods overlap with the standard BooleanMethods methods, and they only
-    # make sense for numbers, they are only included in NumericExpression.
+    # methods overlap with the standard +BooleanMethods methods+, and they only
+    # make sense for integers, they are only included in +NumericExpression+.
+    #
+    #   :a.sql_number & :b # "a" & "b"
+    #   :a.sql_number | :b # "a" | "b"
+    #   :a.sql_number ^ :b # "a" ^ "b"
+    #   :a.sql_number << :b # "a" << "b"
+    #   :a.sql_number >> :b # "a" >> "b"
+    #   ~:a.sql_number # ~"a"
     module BitwiseMethods
       ComplexExpression::BITWISE_OPERATORS.each do |o|
         define_method(o) do |ce|
@@ -203,22 +230,21 @@ module Sequel
       end
 
       # Do the bitwise compliment of the self
+      #
+      #   ~:a.sql_number # ~"a"
       def ~
         NumericExpression.new(:'B~', self)
       end
     end
 
-    # This module includes the methods that are defined on objects that can be 
-    # used in a boolean context in SQL (Symbol, LiteralString, SQL::Function,
-    # and SQL::BooleanExpression).
+    # This module includes the boolean/logical AND (&), OR (|) and NOT (~) operators
+    # that are defined on objects that can be used in a boolean context in SQL
+    # (+Symbol+, +LiteralString+, and <tt>SQL::GenericExpression</tt>).
     #
-    # This defines the ~ (NOT), & (AND), and | (OR) methods.
+    #   :a & :b # "a" AND "b"
+    #   :a | :b # "a" OR "b"
+    #   ~:a # NOT "a"
     module BooleanMethods
-      # Create a new BooleanExpression with NOT, representing the inversion of whatever self represents.
-      def ~
-        BooleanExpression.invert(self)
-      end
-      
       ComplexExpression::BOOLEAN_OPERATOR_METHODS.each do |m, o|
         define_method(m) do |ce|
           case ce
@@ -229,35 +255,52 @@ module Sequel
           end
         end
       end
+      
+      # Create a new BooleanExpression with NOT, representing the inversion of whatever self represents.
+      #
+      #   ~:a # NOT :a
+      def ~
+        BooleanExpression.invert(self)
+      end
     end
 
-    # Holds methods that are used to cast objects to differen SQL types.
+    # Holds methods that are used to cast objects to different SQL types.
     module CastMethods 
       # Cast the reciever to the given SQL type.  You can specify a ruby class as a type,
       # and it is handled similarly to using a database independent type in the schema methods.
+      #
+      #   :a.cast(:integer) # CAST(a AS integer)
+      #   :a.cast(String) # CAST(a AS varchar(255))
       def cast(sql_type)
         Cast.new(self, sql_type)
       end
 
-      # Cast the reciever to the given SQL type (or the database's default integer type if none given),
-      # and return the result as a NumericExpression. 
+      # Cast the reciever to the given SQL type (or the database's default Integer type if none given),
+      # and return the result as a +NumericExpression+, so you can use the bitwise operators
+      # on the result. 
+      #
+      #   :a.cast_numeric # CAST(a AS integer)
+      #   :a.cast_numeric(Float) # CAST(a AS double precision)
       def cast_numeric(sql_type = nil)
         cast(sql_type || Integer).sql_number
       end
 
-      # Cast the reciever to the given SQL type (or the database's default string type if none given),
-      # and return the result as a StringExpression, so you can use +
+      # Cast the reciever to the given SQL type (or the database's default String type if none given),
+      # and return the result as a +StringExpression+, so you can use +
       # directly on the result for SQL string concatenation.
+      #
+      #   :a.cast_string # CAST(a AS varchar(255))
+      #   :a.cast_string(:text) # CAST(a AS text)
       def cast_string(sql_type = nil)
         cast(sql_type || String).sql_string
       end
     end
     
     # Adds methods that allow you to treat an object as an instance of a specific
-    # ComplexExpression subclass.  This is useful if another library
+    # +ComplexExpression+ subclass.  This is useful if another library
     # overrides the methods defined by Sequel.
     #
-    # For example, if Symbol#/ is overridden to produce a string (for
+    # For example, if <tt>Symbol#/</tt> is overridden to produce a string (for
     # example, to make file system path creation easier), the
     # following code will not do what you want:
     #
@@ -269,51 +312,64 @@ module Sequel
     module ComplexExpressionMethods
       # Extract a datetime_part (e.g. year, month) from self:
       #
-      #   :date.extract(:year) # SQL:  extract(year FROM "date")
+      #   :date.extract(:year) # extract(year FROM "date")
       #
       # Also has the benefit of returning the result as a
       # NumericExpression instead of a generic ComplexExpression.
       #
       # The extract function is in the SQL standard, but it doesn't
-      # doesn't use the standard function calling convention.
+      # doesn't use the standard function calling convention, and it
+      # doesn't work on all databases.
       def extract(datetime_part)
         Function.new(:extract, PlaceholderLiteralString.new("#{datetime_part} FROM ?", [self])).sql_number
       end
 
-      # Return a BooleanExpression representation of self.
+      # Return a BooleanExpression representation of +self+.
       def sql_boolean
         BooleanExpression.new(:NOOP, self)
       end
 
-      # Return a NumericExpression representation of self.
+      # Return a NumericExpression representation of +self+.
+      # 
+      #   ~:a # NOT "a"
+      #   ~:a.sql_number # ~"a"
       def sql_number
         NumericExpression.new(:NOOP, self)
       end
 
-      # Return a StringExpression representation of self.
+      # Return a StringExpression representation of +self+.
+      #
+      #   :a + :b # "a" + "b"
+      #   :a.sql_string + :b # "a" || "b"
       def sql_string
         StringExpression.new(:NOOP, self)
       end
     end
 
-    # Includes a method that returns Identifiers.
+    # Includes an +identifier+ method that returns <tt>Identifier</tt>s.
     module IdentifierMethods
-      # Return self wrapped as an identifier.
+      # Return self wrapped as an <tt>SQL::Identifier</tt>.
+      #
+      #   :a__b # "a"."b"
+      #   :a__b.identifier # "a__b"
       def identifier
         Identifier.new(self)
       end
     end
 
-    # This module includes the methods that are defined on objects that can be 
-    # used in a numeric or string context in SQL (Symbol (except on ruby 1.9), LiteralString, 
-    # SQL::Function, and SQL::StringExpression).
+    # This module includes the inequality methods (>, <, >=, <=) that are defined on objects that can be 
+    # used in a numeric or string context in SQL (+Symbol+ (except on ruby 1.9), +LiteralString+, 
+    # <tt>SQL::GenericExpression</tt>).
     #
-    # This defines the >, <, >=, and <= methods.
+    #   'a'.lit > :b # a > "b"
+    #   'a'.lit < :b # a > "b"
+    #   'a'.lit >= :b # a >= "b"
+    #   'a'.lit <= :b # a <= "b"
     module InequalityMethods
       ComplexExpression::INEQUALITY_OPERATORS.each do |o|
         define_method(o) do |ce|
           case ce
-          when BooleanExpression, TrueClass, FalseClass, NilClass, Hash, Array
+          when BooleanExpression, TrueClass, FalseClass, NilClass, Hash, ::Array
             raise(Error, "cannot apply #{o} to a boolean expression")
           else  
             BooleanExpression.new(o, self, ce)
@@ -323,16 +379,17 @@ module Sequel
     end
 
     # This module augments the default initalize method for the 
-    # ComplexExpression subclass it is included in, so that
-    # attempting to use boolean input when initializing a NumericExpression
-    # or StringExpression results in an error.
+    # +ComplexExpression+ subclass it is included in, so that
+    # attempting to use boolean input when initializing a +NumericExpression+
+    # or +StringExpression+ results in an error.  It is not expected to be
+    # used directly.
     module NoBooleanInputMethods
-      # Raise an Error if one of the args would be boolean in an SQL
+      # Raise an +Error+ if one of the args would be boolean in an SQL
       # context, otherwise call super.
       def initialize(op, *args)
         args.each do |a|
           case a
-          when BooleanExpression, TrueClass, FalseClass, NilClass, Hash, Array
+          when BooleanExpression, TrueClass, FalseClass, NilClass, Hash, ::Array
             raise(Error, "cannot apply #{op} to a boolean expression")
           end
         end
@@ -340,11 +397,14 @@ module Sequel
       end
     end
 
-    # This module includes the methods that are defined on objects that can be 
-    # used in a numeric context in SQL (Symbol, LiteralString, SQL::Function,
-    # and SQL::NumericExpression).
+    # This module includes the standard mathematical methods (+, -, *, and /)
+    # that are defined on objects that can be used in a numeric context in SQL
+    # (+Symbol+, +LiteralString+, and +SQL::GenericExpression+).
     #
-    # This defines the +, -, *, and / methods.
+    #   :a + :b # "a" + "b"
+    #   :a - :b # "a" - "b"
+    #   :a * :b # "a" * "b"
+    #   :a / :b # "a" / "b"
     module NumericMethods
       ComplexExpression::MATHEMATICAL_OPERATORS.each do |o|
         define_method(o) do |ce|
@@ -358,66 +418,83 @@ module Sequel
       end
     end
 
-    # Methods that create OrderedExpressions, used for sorting by columns
+    # Methods that create +OrderedExpressions+, used for sorting by columns
     # or more complex expressions.
     module OrderMethods
-      # Mark the receiving SQL column as sorting in a descending fashion.
-      def desc
-        OrderedExpression.new(self)
+      # Mark the receiving SQL column as sorting in an ascending fashion (generally a no-op).
+      # Options:
+      #
+      # :nulls :: Set to :first to use NULLS FIRST (so NULL values are ordered
+      #           before other values), or :last to use NULLS LAST (so NULL values
+      #           are ordered after other values).
+      def asc(opts={})
+        OrderedExpression.new(self, false, opts)
       end
       
-      # Mark the receiving SQL column as sorting in an ascending fashion (generally a no-op).
-      def asc
-        OrderedExpression.new(self, false)
+      # Mark the receiving SQL column as sorting in a descending fashion.
+      # Options:
+      #
+      # :nulls :: Set to :first to use NULLS FIRST (so NULL values are ordered
+      #           before other values), or :last to use NULLS LAST (so NULL values
+      #           are ordered after other values).
+      def desc(opts={})
+        OrderedExpression.new(self, true, opts)
       end
     end
 
-    # Methods that created QualifiedIdentifiers, used for qualifying column
+    # Includes a +qualify+ method that created <tt>QualifiedIdentifier</tt>s, used for qualifying column
     # names with a table or table names with a schema.
     module QualifyingMethods
-      # Qualify the current object with the given table/schema.
-      def qualify(ts)
-        QualifiedIdentifier.new(ts, self)
+      # Qualify the receiver with the given +qualifier+ (table for column/schema for table).
+      #
+      #   :column.qualify(:table) # "table"."column"
+      #   :table.qualify(:schema) # "schema"."table"
+      #   :column.qualify(:table).qualify(:schema) # "schema"."table"."column"
+      def qualify(qualifier)
+        QualifiedIdentifier.new(qualifier, self)
       end
     end
 
-    # This module includes the methods that are defined on objects that can be 
-    # used in a string context in SQL (Symbol, LiteralString, SQL::Function,
-    # and SQL::StringExpression).
-    #
-    # This defines the like (LIKE) and ilike methods, used for pattern matching.
-    # like is case sensitive (if the database supports it), ilike is case insensitive.
+    # This module includes the +like+ and +ilike+ methods used for pattern matching that are defined on objects that can be 
+    # used in a string context in SQL (+Symbol+, +LiteralString+, <tt>SQL::GenericExpression</tt>).
     module StringMethods
-      # Create a BooleanExpression case insensitive pattern match of self
-      # with the given patterns.  See StringExpression.like.
+      # Create a +BooleanExpression+ case insensitive pattern match of the receiver
+      # with the given patterns.  See <tt>StringExpression.like</tt>.
+      #
+      #   :a.ilike('A%') # "a" ILIKE 'A%'
       def ilike(*ces)
         StringExpression.like(self, *(ces << {:case_insensitive=>true}))
       end
 
-      # Create a BooleanExpression case sensitive (if the database supports it) pattern match of self with
-      # the given patterns.  See StringExpression.like.
+      # Create a +BooleanExpression+ case sensitive (if the database supports it) pattern match of the receiver with
+      # the given patterns.  See <tt>StringExpression.like</tt>.
+      #
+      #   :a.like('A%') # "a" LIKE 'A%'
       def like(*ces)
         StringExpression.like(self, *ces)
       end
     end
 
-    # This module is included in StringExpression and can be included elsewhere
-    # to allow the use of the + operator to represent concatenation of SQL
-    # Strings:
-    #
-    #   :x.sql_string + :y => # SQL: x || y
+    # This module includes the <tt>+</tt> method.  It is included in +StringExpression+ and can be included elsewhere
+    # to allow the use of the + operator to represent concatenation of SQL Strings:
     module StringConcatenationMethods
+      # Return a +StringExpression+ representing the concatenation of the receiver
+      # with the given argument.
+      #
+      #   :x.sql_string + :y => # "x" || "y"
       def +(ce)
         StringExpression.new(:'||', self, ce)
       end
     end
 
-    # Methods that create Subscripts (SQL array accesses).
+    # This module includes the +sql_subscript+ method, representing SQL array accesses.
     module SubscriptMethods
-      # Return an SQL array subscript with the given arguments.
+      # Return a <tt>Subscript</tt> with the given arguments, representing an
+      # SQL array access.
       #
-      #   :array.sql_subscript(1) # SQL: array[1]
-      #   :array.sql_subscript(1, 2) # SQL: array[1, 2]
+      #   :array.sql_subscript(1) # array[1]
+      #   :array.sql_subscript(1, 2) # array[1, 2]
+      #   :array.sql_subscript([1, 2]) # array[1, 2]
       def sql_subscript(*sub)
         Subscript.new(self, sub.flatten)
       end
@@ -425,12 +502,12 @@ module Sequel
 
     ### Classes ###
 
-    # Represents an aliasing of an expression/column to a given name.
+    # Represents an aliasing of an expression to a given alias.
     class AliasedExpression < Expression
       # The expression to alias
       attr_reader :expression
 
-      # The alias to use for the expression, not alias since that is
+      # The alias to use for the expression, not +alias+ since that is
       # a keyword in ruby.
       attr_reader :aliaz
 
@@ -442,28 +519,31 @@ module Sequel
       to_s_method :aliased_expression_sql
     end
 
-    # Blob is used to represent binary data in the Ruby environment that is
+    # +Blob+ is used to represent binary data in the Ruby environment that is
     # stored as a blob type in the database. Sequel represents binary data as a Blob object because 
-    # certain database engines require binary data to be escaped.
+    # most database engines require binary data to be escaped differently than regular strings.
     class Blob < ::String
-      # Returns self
+      # Returns +self+, used so that Blobs don't get wrapped in multiple
+      # levels.
       def to_sequel_blob
         self
       end
     end
 
-    # Subclass of ComplexExpression where the expression results
+    # Subclass of +ComplexExpression+ where the expression results
     # in a boolean value in SQL.
     class BooleanExpression < ComplexExpression
       include BooleanMethods
       
-      # Take pairs of values (e.g. a hash or array of arrays of two pairs)
-      # and converts it to a BooleanExpression.  The operator and args
+      # Take pairs of values (e.g. a hash or array of two element arrays)
+      # and converts it to a +BooleanExpression+.  The operator and args
       # used depends on the case of the right (2nd) argument:
       #
       # * 0..10 - left >= 0 AND left <= 10
       # * [1,2] - left IN (1,2)
       # * nil - left IS NULL
+      # * true - left IS TRUE 
+      # * false - left IS FALSE 
       # * /as/ - left ~ 'as'
       # * :blah - left = blah
       # * 'blah' - left = 'blah'
@@ -480,7 +560,7 @@ module Sequel
           ce = case r
           when Range
             new(:AND, new(:>=, l, r.begin), new(r.exclude_end? ? :< : :<=, l, r.end))
-          when Array, ::Sequel::Dataset, SQLArray
+          when ::Array, ::Sequel::Dataset
             new(:IN, l, r)
           when NegativeBooleanConstant
             new(:"IS NOT", l, r.constant)
@@ -502,6 +582,8 @@ module Sequel
       # be inverted, raise an error.  An inverted expression should match everything that the
       # uninverted expression did not match, and vice-versa, except for possible issues with
       # SQL NULL (i.e. 1 == NULL is NULL and 1 != NULL is also NULL).
+      #
+      #   BooleanExpression.invert(:a) # NOT "a"
       def self.invert(ce)
         case ce
         when BooleanExpression
@@ -519,23 +601,31 @@ module Sequel
       end
     end
 
-    # Represents an SQL CASE expression, used for conditions.
+    # Represents an SQL CASE expression, used for conditional branching in SQL.
     class CaseExpression < GenericExpression
       # An array of all two pairs with the first element specifying the
-      # condition and the second element specifying the result.
+      # condition and the second element specifying the result if the
+      # condition matches.
       attr_reader :conditions
 
-      # The default value if no conditions are true
+      # The default value if no conditions match. 
       attr_reader :default
 
       # The expression to test the conditions against
       attr_reader :expression
 
       # Create an object with the given conditions and
-      # default value.
-      def initialize(conditions, default, expression = nil)
+      # default value.  An expression can be provided to
+      # test each condition against, instead of having
+      # all conditions represent their own boolean expression.
+      def initialize(conditions, default, expression=(no_expression=true; nil))
         raise(Sequel::Error, 'CaseExpression conditions must be a hash or array of all two pairs') unless Sequel.condition_specifier?(conditions)
-        @conditions, @default, @expression = conditions.to_a, default, expression
+        @conditions, @default, @expression, @no_expression = conditions.to_a, default, expression, no_expression
+      end
+
+      # Whether to use an expression for this CASE expression.
+      def expression?
+        !@no_expression
       end
 
       to_s_method :case_expression_sql
@@ -578,9 +668,12 @@ module Sequel
       include SubscriptMethods
     end
 
-    # Represents constants or psuedo-constants (e.g. CURRENT_DATE) in SQL.
+    # Represents constants or psuedo-constants (e.g. +CURRENT_DATE+) in SQL.
     class Constant < GenericExpression
-      # Create an object with the given table
+      # The underlying constant related to this object.
+      attr_reader :constant
+
+      # Create an constant with the given value
       def initialize(constant)
         @constant = constant
       end
@@ -588,15 +681,12 @@ module Sequel
       to_s_method :constant_sql, '@constant'
     end
 
-    # Represents boolean constants such as NULL, NOTNULL, TRUE, and FALSE.
+    # Represents boolean constants such as +NULL+, +NOTNULL+, +TRUE+, and +FALSE+.
     class BooleanConstant < Constant
-      # The underlying constant related for this object.
-      attr_reader :constant
-
       to_s_method :boolean_constant_sql, '@constant'
     end
     
-    # Represents inverse boolean constants (currently only NOTNULL). A
+    # Represents inverse boolean constants (currently only +NOTNULL+). A
     # special class to allow for special behavior.
     class NegativeBooleanConstant < BooleanConstant
       to_s_method :negative_boolean_constant_sql, '@constant'
@@ -624,7 +714,7 @@ module Sequel
       # The SQL function to call
       attr_reader :f
       
-      # Set the attributes to the given arguments
+      # Set the functions and args to the given arguments
       def initialize(f, *args)
         @f, @args = f, args
       end
@@ -645,12 +735,12 @@ module Sequel
     end
 
     # Represents an identifier (column or table). Can be used
-    # to specify a Symbol with multiple underscores should not be
+    # to specify a +Symbol+ with multiple underscores should not be
     # split, or for creating an identifier without using a symbol.
     class Identifier < GenericExpression
       include QualifyingMethods
 
-      # The table and column to reference
+      # The table or column to reference
       attr_reader :value
 
       # Set the value to the given argument
@@ -680,7 +770,7 @@ module Sequel
       to_s_method :join_clause_sql
     end
 
-    # Represents an SQL JOIN table ON conditions clause.
+    # Represents an SQL JOIN clause with ON conditions.
     class JoinOnClause < JoinClause
       # The conditions for the join
       attr_reader :on
@@ -695,7 +785,7 @@ module Sequel
       to_s_method :join_on_clause_sql
     end
 
-    # Represents an SQL JOIN table USING (columns) clause.
+    # Represents an SQL JOIN clause with USING conditions.
     class JoinUsingClause < JoinClause
       # The columns that appear in both tables that should be equal 
       # for the conditions to match.
@@ -713,8 +803,9 @@ module Sequel
 
     # Represents a literal string with placeholders and arguments.
     # This is necessary to ensure delayed literalization of the arguments
-    # required for the prepared statement support
-    class PlaceholderLiteralString < Expression
+    # required for the prepared statement support and for database-specific
+    # literalization.
+    class PlaceholderLiteralString < GenericExpression
       # The arguments that will be subsituted into the placeholders.
       # Either an array of unnamed placeholders (which will be substituted in
       # order for ? characters), or a hash of named placeholders (which will be
@@ -737,7 +828,7 @@ module Sequel
       to_s_method :placeholder_literal_string_sql
     end
 
-    # Subclass of ComplexExpression where the expression results
+    # Subclass of +ComplexExpression+ where the expression results
     # in a numeric value in SQL.
     class NumericExpression < ComplexExpression
       include BitwiseMethods 
@@ -748,43 +839,51 @@ module Sequel
 
     # Represents a column/expression to order the result set by.
     class OrderedExpression < Expression
+      INVERT_NULLS = {:first=>:last, :last=>:first}.freeze
+
       # The expression to order the result set by.
       attr_reader :expression
 
       # Whether the expression should order the result set in a descending manner
       attr_reader :descending
 
+      # Whether to sort NULLS FIRST/LAST
+      attr_reader :nulls
+
       # Set the expression and descending attributes to the given values.
-      def initialize(expression, descending = true)
-        @expression, @descending = expression, descending
+      # Options:
+      #
+      # :nulls :: Can be :first/:last for NULLS FIRST/LAST.
+      def initialize(expression, descending = true, opts={})
+        @expression, @descending, @nulls = expression, descending, opts[:nulls]
       end
 
-      # Return a copy that is ASC
+      # Return a copy that is ordered ASC
       def asc
-        OrderedExpression.new(@expression, false)
+        OrderedExpression.new(@expression, false, :nulls=>@nulls)
       end
 
-      # Return a copy that is DESC
+      # Return a copy that is ordered DESC
       def desc
-        OrderedExpression.new(@expression)
+        OrderedExpression.new(@expression, true, :nulls=>@nulls)
       end
 
-      # Return an inverted expression, changing ASC to DESC and vice versa
+      # Return an inverted expression, changing ASC to DESC and NULLS FIRST to NULLS LAST.
       def invert
-        OrderedExpression.new(@expression, !@descending)
+        OrderedExpression.new(@expression, !@descending, :nulls=>INVERT_NULLS.fetch(@nulls, @nulls))
       end
 
       to_s_method :ordered_expression_sql
     end
 
-    # Represents a qualified (column with table or table with schema) reference. 
+    # Represents a qualified identifier (column with table or table with schema).
     class QualifiedIdentifier < GenericExpression
       include QualifyingMethods
 
-      # The column to reference
+      # The column/table referenced
       attr_reader :column
 
-      # The table to reference
+      # The table/schema qualifying the reference
       attr_reader :table
 
       # Set the table and column to the given arguments
@@ -795,7 +894,7 @@ module Sequel
       to_s_method :qualified_identifier_sql
     end
     
-    # Subclass of ComplexExpression where the expression results
+    # Subclass of +ComplexExpression+ where the expression results
     # in a text/string/varchar value in SQL.
     class StringExpression < ComplexExpression
       include StringMethods
@@ -803,23 +902,31 @@ module Sequel
       include InequalityMethods
       include NoBooleanInputMethods
 
-      # Map of [regexp, case_insenstive] to ComplexExpression operator
+      # Map of [regexp, case_insenstive] to +ComplexExpression+ operator symbol
       LIKE_MAP = {[true, true]=>:'~*', [true, false]=>:~, [false, true]=>:ILIKE, [false, false]=>:LIKE}
       
       # Creates a SQL pattern match exprssion. left (l) is the SQL string we
       # are matching against, and ces are the patterns we are matching.
-      # The match succeeds if any of the patterns match (SQL OR).  Patterns
-      # can be given as strings or regular expressions.  Strings will cause
-      # the SQL LIKE operator to be used, and should be supported by most
-      # databases.  Regular expressions will probably only work on MySQL
-      # and PostgreSQL, and SQL regular expression syntax is not fully compatible
-      # with ruby regular expression syntax, so be careful if using regular
-      # expressions.
+      # The match succeeds if any of the patterns match (SQL OR).
+      #
+      # If a regular expression is used as a pattern, an SQL regular expression will be
+      # used, which is currently only supported on MySQL and PostgreSQL.  Be aware
+      # that MySQL and PostgreSQL regular expression syntax is similar to ruby
+      # regular expression syntax, but it not exactly the same, especially for
+      # advanced regular expression features.  Sequel just uses the source of the
+      # ruby regular expression verbatim as the SQL regular expression string.
+      #
+      # If any other object is used as a regular expression, the SQL LIKE operator will
+      # be used, and should be supported by most databases.  
       # 
       # The pattern match will be case insensitive if the last argument is a hash
       # with a key of :case_insensitive that is not false or nil. Also,
       # if a case insensitive regular expression is used (//i), that particular
       # pattern which will always be case insensitive.
+      #
+      #   StringExpression.like(:a, 'a%') # "a" LIKE 'a%'
+      #   StringExpression.like(:a, 'a%', :case_insensitive=>true) # "a" ILIKE 'a%'
+      #   StringExpression.like(:a, 'a%', /^a/i) # "a" LIKE 'a%' OR "a" ~* '^a' 
       def self.like(l, *ces)
         l, lre, lci = like_element(l)
         lci = (ces.last.is_a?(Hash) ? ces.pop : {})[:case_insensitive] ? true : lci
@@ -830,7 +937,7 @@ module Sequel
         ces.length == 1 ? ces.at(0) : BooleanExpression.new(:OR, *ces)
       end
       
-      # An array of three parts:
+      # Returns a three element array, made up of:
       # * The object to use
       # * Whether it is a regular expression
       # * Whether it is case insensitive
@@ -844,22 +951,6 @@ module Sequel
       private_class_method :like_element
     end
 
-    # Represents an SQL array.  Added so it is possible to deal with a
-    # ruby array of all two pairs as an SQL array instead of an ordered
-    # hash-like conditions specifier.
-    class SQLArray < Expression
-      # The array of objects this SQLArray wraps
-      attr_reader :array
-      alias to_a array
-
-      # Create an object with the given array.
-      def initialize(array)
-        @array = array
-      end
-
-      to_s_method :array_sql, '@array'
-    end
-
     # Represents an SQL array access, with multiple possible arguments.
     class Subscript < GenericExpression
       # The SQL array column
@@ -873,7 +964,7 @@ module Sequel
         @f, @sub = f, sub
       end
 
-      # Create a new subscript appending the given subscript(s)
+      # Create a new +Subscript+ appending the given subscript(s)
       # the the current array of subscripts.
       def |(sub)
         Subscript.new(@f, @sub + Array(sub))
@@ -882,32 +973,48 @@ module Sequel
       to_s_method :subscript_sql
     end
 
-    # The purpose of this class is to allow the easy creation of SQL identifiers and functions
-    # without relying on methods defined on Symbol.  This is useful if another library defines
-    # the methods defined by Sequel, or if you are running on ruby 1.9.
+    # Represents an SQL value list (IN/NOT IN predicate value).  Added so it is possible to deal with a
+    # ruby array of two element arrays as an SQL value list instead of an ordered
+    # hash-like conditions specifier.
+    class ValueList < ::Array
+    end
+
+    # Deprecated name for +ValueList+, used for backwards compatibility
+    SQLArray = ValueList
+
+    # The purpose of the +VirtualRow+ class is to allow the easy creation of SQL identifiers and functions
+    # without relying on methods defined on +Symbol+.  This is useful if another library defines
+    # the methods defined by Sequel, if you are running on ruby 1.9, or if you are not using the
+    # core extensions.
     #
-    # An instance of this class is yielded to the block supplied to filter, order, and select.
+    # An instance of this class is yielded to the block supplied to <tt>Dataset#filter</tt>, <tt>Dataset#order</tt>, and <tt>Dataset#select</tt>
+    # (and the other methods that accept a block and pass it to one of those methods).
     # If the block doesn't take an argument, the block is instance_evaled in the context of
     # a new instance of this class.
     #
-    # VirtualRow uses method_missing to return Identifiers, QualifiedIdentifiers, Functions, or WindowFunctions, 
-    # depending on how it is called.  If a block is not given, creates one of the following objects:
-    # * Function - returned if any arguments are supplied, using the method name
-    #   as the function name, and the arguments as the function arguments.
-    # * QualifiedIdentifier - returned if the method name contains __, with the
-    #   table being the part before __, and the column being the part after.
-    # * Identifier - returned otherwise, using the method name.
-    # If a block is given, it returns either a Function or WindowFunction, depending on the first
+    # +VirtualRow+ uses +method_missing+ to return either an +Identifier+, +QualifiedIdentifier+, +Function+, or +WindowFunction+, 
+    # depending on how it is called.
+    #
+    # If a block is _not_ given, creates one of the following objects:
+    #
+    # +Function+ :: Returned if any arguments are supplied, using the method name
+    #               as the function name, and the arguments as the function arguments.
+    # +QualifiedIdentifier+ :: Returned if the method name contains __, with the
+    #                          table being the part before __, and the column being the part after.
+    # +Identifier+ :: Returned otherwise, using the method name.
+    #
+    # If a block is given, it returns either a +Function+ or +WindowFunction+, depending on the first
     # argument to the method.  Note that the block is currently not called by the code, though
     # this may change in a future version.  If the first argument is:
-    # * no arguments given - uses a Function with no arguments.
-    # * :* - uses a Function with a literal wildcard argument (*), mostly useful for COUNT.
-    # * :distinct - uses a Function that prepends DISTINCT to the rest of the arguments, mostly
-    #   useful for aggregate functions.
-    # * :over - uses a WindowFunction.  If a second argument is provided, it should be a hash
-    #   of options which are passed to Window (e.g. :window, :partition, :order, :frame).  The
-    #   arguments to the function itself should be specified as :*=>true for a wildcard, or via
-    #   the :args option.
+    #
+    # no arguments given :: creates a +Function+ with no arguments.
+    # :* :: creates a +Function+ with a literal wildcard argument (*), mostly useful for COUNT.
+    # :distinct :: creates a +Function+ that prepends DISTINCT to the rest of the arguments, mostly
+    #              useful for aggregate functions.
+    # :over :: creates a +WindowFunction+.  If a second argument is provided, it should be a hash
+    #          of options which are passed to Window (with possible keys :window, :partition, :order, and :frame).  The
+    #          arguments to the function itself should be specified as <tt>:*=>true</tt> for a wildcard, or via
+    #          the <tt>:args</tt> option.
     #
     # Examples:
     #
@@ -927,13 +1034,15 @@ module Sequel
     #   ds.select{rank(:over){}} # SELECT rank() OVER () FROM t
     #   ds.select{count(:over, :*=>true){}} # SELECT count(*) OVER () FROM t
     #   ds.select{sum(:over, :args=>col1, :partition=>col2, :order=>col3){}} # SELECT sum(col1) OVER (PARTITION BY col2 ORDER BY col3) FROM t
+    #
+    # For a more detailed explanation, see the {Virtual Rows guide}[link:files/doc/virtual_rows_rdoc.html].
     class VirtualRow < BasicObject
       WILDCARD = LiteralString.new('*').freeze
       QUESTION_MARK = LiteralString.new('?').freeze
       COMMA_SEPARATOR = LiteralString.new(', ').freeze
       DOUBLE_UNDERSCORE = '__'.freeze
 
-      # Return Identifiers, QualifiedIdentifiers, Functions, or WindowFunctions, depending
+      # Return an +Identifier+, +QualifiedIdentifier+, +Function+, or +WindowFunction+, depending
       # on arguments and whether a block is provided.  Does not currently call the block.
       # See the class level documentation.
       def method_missing(m, *args, &block)
@@ -963,17 +1072,17 @@ module Sequel
       end
     end
 
-    # A window is part of a window function specifying the window over which the function operates.
-    # It is separated from the WindowFunction class because it also can be used separately on
+    # A +Window+ is part of a window function specifying the window over which the function operates.
+    # It is separated from the +WindowFunction+ class because it also can be used separately on
     # some databases.
     class Window < Expression
-      # The options for this window.  Options currently used are:
-      # * :frame - if specified, should be :all or :rows.  :all always operates over all rows in the
-      #   partition, while :rows excludes the current row's later peers.  The default is to include
-      #   all previous rows in the partition up to the current row's last peer.
-      # * :order - order on the column(s) given
-      # * :partition - partition/group on the column(s) given
-      # * :window - base results on a previously specified named window
+      # The options for this window.  Options currently supported:
+      # :frame :: if specified, should be :all, :rows, or a String that is used literally. :all always operates over all rows in the
+      #           partition, while :rows excludes the current row's later peers.  The default is to include
+      #           all previous rows in the partition up to the current row's last peer.
+      # :order :: order on the column(s) given
+      # :partition :: partition/group on the column(s) given
+      # :window :: base results on a previously specified named window
       attr_reader :opts
 
       # Set the options to the options given
@@ -984,12 +1093,12 @@ module Sequel
       to_s_method :window_sql, '@opts'
     end
 
-    # A WindowFunction is a grouping of a function with a window over which it operates.
+    # A +WindowFunction+ is a grouping of a +Function+ with a +Window+ over which it operates.
     class WindowFunction < GenericExpression
-      # The function to use, should be an SQL::Function.
+      # The function to use, should be an <tt>SQL::Function</tt>.
       attr_reader :function
 
-      # The window to use, should be an SQL::Window.
+      # The window to use, should be an <tt>SQL::Window</tt>.
       attr_reader :window
 
       # Set the function and window.
@@ -1001,9 +1110,9 @@ module Sequel
     end
   end
 
-  # LiteralString is used to represent literal SQL expressions. A 
-  # LiteralString is copied verbatim into an SQL statement. Instances of
-  # LiteralString can be created by calling String#lit.
+  # +LiteralString+ is used to represent literal SQL expressions. A 
+  # +LiteralString+ is copied verbatim into an SQL statement. Instances of
+  # +LiteralString+ can be created by calling <tt>String#lit</tt>.
   class LiteralString
     include SQL::OrderMethods
     include SQL::ComplexExpressionMethods