sequel 2.11.0 → 2.12.0

data/lib/{sequel_core → sequel}/dataset/convenience.rb

@@ -3,13 +3,19 @@ module Sequel
     COMMA_SEPARATOR = ', '.freeze
     COUNT_OF_ALL_AS_COUNT = SQL::Function.new(:count, LiteralString.new('*'.freeze)).as(:count)
 
-    # Returns the first record matching the conditions.
+    # Returns the first record matching the conditions. Examples:
+    #
+    #   ds[:id=>1] => {:id=1}
     def [](*conditions)
+      Deprecation.deprecate('Using an Integer argument to Dataset#[] is deprecated and will raise an error in Sequel 3.0. Use Dataset#first.') if conditions.length == 1 and conditions.is_a?(Integer)
+      Deprecation.deprecate('Using Dataset#[] without an argument is deprecated and will raise an error in Sequel 3.0. Use Dataset#first.') if conditions.length == 0
       first(*conditions)
     end
 
     # Update all records matching the conditions
-    # with the values specified.
+    # with the values specified. Examples:
+    #
+    #   ds[:id=>1] = {:id=>2} # SQL: UPDATE ... SET id = 2 WHERE id = 1
     def []=(conditions, values)
       filter(conditions).update(values)
     end
@@ -19,20 +25,18 @@ module Sequel
       get{|o| o.avg(column)}
     end
     
-    # Returns true if no records exists in the dataset
+    # Returns true if no records exist in the dataset, false otherwise
     def empty?
       get(1).nil?
     end
     
-    # Returns the first record in the dataset. If a numeric argument is
+    # If a integer argument is
     # given, it is interpreted as a limit, and then returns all 
     # matching records up to that limit.  If no argument is passed,
     # it returns the first matching record.  If any other type of
     # argument(s) is passed, it is given to filter and the
     # first matching record is returned. If a block is given, it is used
-    # to filter the dataset before returning anything.
-    #
-    # Examples:
+    # to filter the dataset before returning anything.  Examples:
     # 
     #   ds.first => {:id=>7}
     #   ds.first(2) => [{:id=>6}, {:id=>4}]
@@ -61,16 +65,74 @@ module Sequel
     end
 
     # Return the column value for the first matching record in the dataset.
+    # Raises an error if both an argument and block is given.
+    #
+    #   ds.get(:id)
+    #   ds.get{|o| o.sum(:id)}
     def get(column=nil, &block)
       raise(Error, 'must provide argument or block to Dataset#get, not both') if column && block
       (column ? select(column) : select(&block)).single_value
     end
 
-    # Returns a dataset grouped by the given column with count by group.
+    # Returns a dataset grouped by the given column with count by group,
+    # order by the count of records.  Examples:
+    #
+    #   ds.group_and_count(:name) => [{:name=>'a', :count=>1}, ...]
+    #   ds.group_and_count(:first_name, :last_name) => [{:first_name=>'a', :last_name=>'b', :count=>1}, ...]
     def group_and_count(*columns)
       group(*columns).select(*(columns + [COUNT_OF_ALL_AS_COUNT])).order(:count)
     end
     
+    # Inserts multiple records into the associated table. This method can be
+    # to efficiently insert a large amounts of records into a table. Inserts
+    # are automatically wrapped in a transaction.
+    # 
+    # This method is called with a columns array and an array of value arrays:
+    #
+    #   dataset.import([:x, :y], [[1, 2], [3, 4]])
+    #
+    # This method also accepts a dataset instead of an array of value arrays:
+    #
+    #   dataset.import([:x, :y], other_dataset.select(:a___x, :b___y))
+    #
+    # The method also accepts a :slice or :commit_every option that specifies
+    # the number of records to insert per transaction. This is useful especially
+    # when inserting a large number of records, e.g.:
+    #
+    #   # this will commit every 50 records
+    #   dataset.import([:x, :y], [[1, 2], [3, 4], ...], :slice => 50)
+    def import(*args)
+      if args.empty?
+        Sequel::Deprecation.deprecate('Calling Sequel::Dataset#import with no arguments', 'Use dataset.multi_insert([])')
+        return
+      elsif args[0].is_a?(Array) && args[1].is_a?(Array)
+        columns, values, opts = *args
+      elsif args[0].is_a?(Array) && args[1].is_a?(Dataset)
+        table = @opts[:from].first
+        columns, dataset = *args
+        sql = "INSERT INTO #{quote_identifier(table)} (#{identifier_list(columns)}) VALUES #{literal(dataset)}"
+        return @db.transaction{execute_dui(sql)}
+      else
+        Sequel::Deprecation.deprecate('Calling Sequel::Dataset#import with hashes', 'Use Sequel::Dataset#multi_insert')
+        return multi_insert(*args)
+      end
+      # make sure there's work to do
+      Sequel::Deprecation.deprecate('Calling Sequel::Dataset#import an empty column array is deprecated and will raise an error in Sequel 3.0.') if columns.empty?
+      return if columns.empty? || values.empty?
+      
+      slice_size = opts && (opts[:commit_every] || opts[:slice])
+      
+      if slice_size
+        values.each_slice(slice_size) do |slice|
+          statements = multi_insert_sql(columns, slice)
+          @db.transaction(opts){statements.each{|st| execute_dui(st)}}
+        end
+      else
+        statements = multi_insert_sql(columns, values)
+        @db.transaction{statements.each{|st| execute_dui(st)}}
+      end
+    end
+    
     # Returns the interval between minimum and maximum values for the given 
     # column.
     def interval(column)
@@ -87,10 +149,15 @@ module Sequel
     end
     
     # Maps column values for each record in the dataset (if a column name is
-    # given), or performs the stock mapping functionality of Enumerable.
-    def map(column_name = nil, &block)
-      if column_name
-        super() {|r| r[column_name]}
+    # given), or performs the stock mapping functionality of Enumerable. 
+    # Raises an error if both an argument and block are given. Examples:
+    #
+    #   ds.map(:id) => [1, 2, 3, ...]
+    #   ds.map{|r| r[:id] * 2} => [2, 4, 6, ...]
+    def map(column=nil, &block)
+      Deprecation.deprecate('Using Dataset#map with an argument and a block is deprecated and will raise an error in Sequel 3.0. Use an argument or a block, not both.') if column && block
+      if column
+        super(){|r| r[column]}
       else
         super(&block)
       end
@@ -106,38 +173,23 @@ module Sequel
       get{|o| o.min(column)}
     end
 
-    # Inserts multiple records into the associated table. This method can be
-    # to efficiently insert a large amounts of records into a table. Inserts
-    # are automatically wrapped in a transaction.
-    # 
-    # This method should be called with a columns array and an array of value arrays:
-    #
-    #   dataset.multi_insert([:x, :y], [[1, 2], [3, 4]])
-    #
-    # This method can also be called with an array of hashes:
+    # This is a front end for import that allows you to submit an array of
+    # hashes instead of arrays of columns and values:
     # 
-    #   dataset.multi_insert({:x => 1}, {:x => 2})
+    #   dataset.multi_insert([{:x => 1}, {:x => 2}])
     #
     # Be aware that all hashes should have the same keys if you use this calling method,
     # otherwise some columns could be missed or set to null instead of to default
     # values.
     #
-    # The method also accepts a :slice or :commit_every option that specifies
-    # the number of records to insert per transaction. This is useful especially
-    # when inserting a large number of records, e.g.:
-    #
-    #   # this will commit every 50 records
-    #   dataset.multi_insert(lots_of_records, :slice => 50)
+    # You can also use the :slice or :commit_every option that import accepts.
     def multi_insert(*args)
       if args.empty?
+        Sequel::Deprecation.deprecate('Calling Sequel::Dataset#multi_insert with no arguments', 'Use dataset.multi_insert([])')
         return
-      elsif args[0].is_a?(Array) && args[1].is_a?(Array)
-        columns, values, opts = *args
-      elsif args[0].is_a?(Array) && args[1].is_a?(Dataset)
-        table = @opts[:from].first
-        columns, dataset = *args
-        sql = "INSERT INTO #{quote_identifier(table)} (#{identifier_list(columns)}) VALUES #{literal(dataset)}"
-        return @db.transaction{execute_dui(sql)}
+      elsif args[0].is_a?(Array) && (args[1].is_a?(Array) || args[1].is_a?(Dataset))
+        Sequel::Deprecation.deprecate('Calling Sequel::Dataset#multi_insert with an array of columns and an array of arrays of values', 'Use Sequel::Dataset#import')
+       return import(*args)
       else
         # we assume that an array of hashes is given
         hashes, opts = *args
@@ -146,28 +198,9 @@ module Sequel
         # convert the hashes into arrays
         values = hashes.map {|h| columns.map {|c| h[c]}}
       end
-      # make sure there's work to do
-      return if columns.empty? || values.empty?
-      
-      slice_size = opts && (opts[:commit_every] || opts[:slice])
-      
-      if slice_size
-        values.each_slice(slice_size) do |slice|
-          statements = multi_insert_sql(columns, slice)
-          @db.transaction{statements.each{|st| execute_dui(st)}}
-        end
-      else
-        statements = multi_insert_sql(columns, values)
-        @db.transaction{statements.each{|st| execute_dui(st)}}
-      end
-    end
-    alias_method :import, :multi_insert
-    
-    # Pretty prints the records in the dataset as plain-text table.
-    def print(*cols)
-      Sequel::PrettyTable.print(naked.all, cols.empty? ? columns : cols)
+      import(columns, values, opts)
     end
-    
+
     # Returns a Range object made from the minimum and maximum values for the
     # given column.
     def range(column)
@@ -177,15 +210,20 @@ module Sequel
     end
     
     # Returns the first record in the dataset.
-    def single_record(opts = nil)
-      each((opts||{}).merge(:limit=>1)){|r| return r}
+    def single_record(opts = (defarg=true;nil))
+      Deprecation.deprecate("Calling Dataset#single_record with an argument is deprecated and will raise an error in Sequel 3.0.  Use dataset.clone(opts).single_record.") unless defarg
+      ds = clone(:limit=>1)
+      opts = opts.merge(:limit=>1) if opts and opts[:limit]
+      defarg ? ds.each{|r| return r} : ds.each(opts){|r| return r}
       nil
     end
 
     # Returns the first value of the first record in the dataset.
     # Returns nil if dataset is empty.
-    def single_value(opts = nil)
-      if r = single_record((opts||{}).merge(:graph=>false, :naked=>true))
+    def single_value(opts = (defarg=true;nil))
+      Deprecation.deprecate("Calling Dataset#single_value with an argument is deprecated and will raise an error in Sequel 3.0.  Use dataset.clone(opts).single_value.") unless defarg
+      ds = naked.clone(:graph=>false)
+      if r = (defarg ? ds.single_record : ds.single_record(opts))
         r.values.first
       end
     end
@@ -213,7 +251,7 @@ module Sequel
     #
     # This does not use a CSV library or handle quoting of values in
     # any way.  If any values in any of the rows could include commas or line
-    # endings, you probably shouldn't use this.
+    # endings, you shouldn't use this.
     def to_csv(include_column_titles = true)
       n = naked
       cols = n.columns

data/lib/{sequel_core/object_graph.rb → sequel/dataset/graph.rb}

@@ -9,7 +9,7 @@ module Sequel
     #   # CREATE TABLE artists (id INTEGER, name TEXT);
     #   # CREATE TABLE albums (id INTEGER, name TEXT, artist_id INTEGER);
     #   DB[:artists].left_outer_join(:albums, :artist_id=>:id).first
-    #   => {:id=>(albums.id||artists.id), :name=>(albums.name||artist.names), :artist_id=>albums.artist_id}
+    #   => {:id=>albums.id, :name=>albums.name, :artist_id=>albums.artist_id}
     #   DB[:artists].graph(:albums, :artist_id=>:id).first
     #   => {:artists=>{:id=>artists.id, :name=>artists.name}, :albums=>{:id=>albums.id, :name=>albums.name, :artist_id=>albums.artist_id}}
     #
@@ -30,7 +30,7 @@ module Sequel
     #
     # Arguments:
     # * dataset -  Can be a symbol (specifying a table), another dataset,
-    #   or an object that responds to .dataset and yields a symbol or a dataset
+    #   or an object that responds to .dataset and return a symbol or a dataset
     # * join_conditions - Any condition(s) allowed by join_table.
     # * options -  A hash of graph options.  The following options are currently used:
     #   * :implicit_qualifier - The qualifier of implicit conditions, see #join_table.
@@ -97,7 +97,7 @@ module Sequel
           select = opts[:select] = []
           columns.each do |column|
             column_aliases[column] = [master, column]
-            select.push(column.qualify(master))
+            select.push(SQL::QualifiedIdentifier.new(master, column))
           end
         end
       end
@@ -129,9 +129,9 @@ module Sequel
               column_alias = :"#{column_alias}_#{column_alias_num}" 
               ca_num[column_alias] += 1
             end
-            [column_alias, column.qualify(table_alias).as(column_alias)]
+            [column_alias, SQL::QualifiedIdentifier.new(table_alias, column).as(column_alias)]
           else
-            [column, column.qualify(table_alias)]
+            [column, SQL::QualifiedIdentifier.new(table_alias, column)]
           end
           column_aliases[col_alias] = [table_alias, column]
           select.push(identifier)
@@ -147,14 +147,16 @@ module Sequel
     # graphed dataset, and must be used instead of .select whenever
     # graphing is used. Example:
     #
-    #   DB[:artists].graph(:albums, :artist_id=>:id).set_graph_aliases(:artist_name=>[:artists, :name], :album_name=>[:albums, :name]).first
-    #   => {:artists=>{:name=>artists.name}, :albums=>{:name=>albums.name}}
+    #   DB[:artists].graph(:albums, :artist_id=>:id).set_graph_aliases(:artist_name=>[:artists, :name], :album_name=>[:albums, :name], :forty_two=>[:albums, :fourtwo, 42]).first
+    #   => {:artists=>{:name=>artists.name}, :albums=>{:name=>albums.name, :fourtwo=>42}}
     #
     # Arguments:
     # * graph_aliases - Should be a hash with keys being symbols of
-    #   column aliases, and values being arrays with two symbol elements.
-    #   The first element of the array should be the table alias,
-    #   and the second should be the actual column name.
+    #   column aliases, and values being arrays with two or three elements.
+    #   The first element of the array should be the table alias symbol,
+    #   and the second should be the actual column name symbol. If the array
+    #   has a third element, it is used as the value returned, instead of
+    #   table_alias.column_name.
     def set_graph_aliases(graph_aliases)
       ds = select(*graph_alias_columns(graph_aliases))
       ds.opts[:graph_aliases] = graph_aliases
@@ -175,7 +177,7 @@ module Sequel
     # Transform the hash of graph aliases to an array of columns
     def graph_alias_columns(graph_aliases)
       graph_aliases.collect do |col_alias, tc| 
-        identifier = tc[2] || tc[1].qualify(tc[0])
+        identifier = tc[2] || SQL::QualifiedIdentifier.new(tc[0], tc[1])
         identifier = SQL::AliasedExpression.new(identifier, col_alias) if tc[2] or tc[1] != col_alias
         identifier
       end
@@ -184,7 +186,7 @@ module Sequel
     # Fetch the rows, split them into component table parts,
     # tranform and run the row_proc on each part (if applicable),
     # and yield a hash of the parts.
-    def graph_each(opts, &block)
+    def graph_each(opts=(defarg=true;nil), &block)
       # Reject tables with nil datasets, as they are excluded from
       # the result set
       datasets = @opts[:graph][:table_aliases].to_a.reject{|ta,ds| ds.nil?}
@@ -198,7 +200,7 @@ module Sequel
       # Use the manually set graph aliases, if any, otherwise
       # use the ones automatically created by .graph
       column_aliases = @opts[:graph_aliases] || @opts[:graph][:column_aliases]
-      fetch_rows(select_sql(opts)) do |r|
+      fetch_rows(defarg ? select_sql : select_sql(opts)) do |r|
         graph = {}
         # Create the sub hashes, one per table
         table_aliases.each{|ta| graph[ta]={}}
@@ -213,7 +215,7 @@ module Sequel
         # row_proc if applicable
         datasets.each do |ta,ds,tr,rp|
           g = graph[ta]
-          graph[ta] = if g.values.any?
+          graph[ta] = if g.values.any?{|x| !x.nil?}
             g = ds.transform_load(g) if tr
             g = rp[g] if rp
             g

data/lib/{sequel_core → sequel}/dataset/prepared_statements.rb

@@ -77,7 +77,7 @@ module Sequel
         when :select, :all
           select_sql
         when :first
-          select_sql(:limit=>1)
+          clone(:limit=>1).select_sql
         when :insert
           insert_sql(@prepared_modify_values)
         when :update

data/lib/{sequel_core → sequel}/dataset/sql.rb

@@ -7,6 +7,8 @@ module Sequel
     COLUMN_REF_RE2 = /\A([\w ]+)___([\w ]+)\z/.freeze
     COLUMN_REF_RE3 = /\A([\w ]+)__([\w ]+)\z/.freeze
     COUNT_FROM_SELF_OPTS = [:distinct, :group, :sql, :limit, :compounds]
+    IS_LITERALS = {nil=>'NULL'.freeze, true=>'TRUE'.freeze, false=>'FALSE'.freeze}.freeze
+    IS_OPERATORS = ::Sequel::SQL::ComplexExpression::IS_OPERATORS
     N_ARITY_OPERATORS = ::Sequel::SQL::ComplexExpression::N_ARITY_OPERATORS
     NULL = "NULL".freeze
     QUESTION_MARK = '?'.freeze
@@ -18,8 +20,10 @@ module Sequel
     # Adds an further filter to an existing filter using AND. If no filter 
     # exists an error is raised. This method is identical to #filter except
     # it expects an existing filter.
+    #
+    #   ds.filter(:a).and(:b) # SQL: WHERE a AND b
     def and(*cond, &block)
-      raise(Error::NoExistingFilter, "No existing filter found.") unless @opts[:having] || @opts[:where]
+      raise(InvalidOperation, "No existing filter found.") unless @opts[:having] || @opts[:where]
       filter(*cond, &block)
     end
 
@@ -56,6 +60,9 @@ module Sequel
     # SQL fragment for complex expressions
     def complex_expression_sql(op, args)
       case op
+      when *IS_OPERATORS
+        v = IS_LITERALS[args.at(1)] || raise(Error, 'Invalid argument used for IS operator')
+        "(#{literal(args.at(0))} #{op} #{v})"
       when *TWO_ARITY_OPERATORS
         "(#{literal(args.at(0))} #{op} #{literal(args.at(1))})"
       when *N_ARITY_OPERATORS
@@ -73,23 +80,23 @@ module Sequel
 
     # Returns the number of records in the dataset.
     def count
-      options_overlap(COUNT_FROM_SELF_OPTS) ? from_self.count : single_value(STOCK_COUNT_OPTS).to_i
+      options_overlap(COUNT_FROM_SELF_OPTS) ? from_self.count : clone(STOCK_COUNT_OPTS).single_value.to_i
     end
-    alias_method :size, :count
 
     # Formats a DELETE statement using the given options and dataset options.
     # 
     #   dataset.filter{|o| o.price >= 100}.delete_sql #=>
     #     "DELETE FROM items WHERE (price >= 100)"
-    def delete_sql(opts = nil)
+    def delete_sql(opts = (defarg=true;nil))
+      Deprecation.deprecate("Calling Dataset#delete_sql with an argument is deprecated and will raise an error in Sequel 3.0.  Use dataset.clone(opts).delete_sql.") unless defarg
       opts = opts ? @opts.merge(opts) : @opts
 
       return static_sql(opts[:sql]) if opts[:sql]
 
       if opts[:group]
-        raise Error::InvalidOperation, "Grouped datasets cannot be deleted from"
+        raise InvalidOperation, "Grouped datasets cannot be deleted from"
       elsif opts[:from].is_a?(Array) && opts[:from].size > 1
-        raise Error::InvalidOperation, "Joined datasets cannot be deleted from"
+        raise InvalidOperation, "Joined datasets cannot be deleted from"
       end
 
       sql = "DELETE FROM #{source_list(opts[:from])}"
@@ -101,6 +108,18 @@ module Sequel
       sql
     end
 
+    # Returns a copy of the dataset with the SQL DISTINCT clause.
+    # The DISTINCT clause is used to remove duplicate rows from the
+    # output.  If arguments are provided, uses a DISTINCT ON clause,
+    # in which case it will only be distinct on those columns, instead
+    # of all returned columns.
+    #
+    #  dataset.distinct # SQL: SELECT DISTINCT * FROM items
+    #  dataset.order(:id).distinct(:id) # SQL: SELECT DISTINCT ON (id) * FROM items ORDER BY id
+    def distinct(*args)
+      clone(:distinct => args)
+    end
+
     # Adds an EXCEPT clause using a second dataset object. If all is true the
     # clause used is EXCEPT ALL, which may return duplicate rows.
     #
@@ -117,7 +136,7 @@ module Sequel
     def exclude(*cond, &block)
       clause = (@opts[:having] ? :having : :where)
       cond = cond.first if cond.size == 1
-      cond = cond.sql_or if (Hash === cond) || ((Array === cond) && (cond.all_two_pairs?))
+      cond = SQL::BooleanExpression.from_value_pairs(cond, :OR) if Sequel.condition_specifier?(cond)
       cond = filter_expr(cond, &block)
       cond = SQL::BooleanExpression.invert(cond)
       cond = SQL::BooleanExpression.new(:AND, @opts[clause], cond) if @opts[clause]
@@ -128,17 +147,18 @@ module Sequel
     #
     #   DB.select(1).where(DB[:items].exists).sql
     #   #=> "SELECT 1 WHERE EXISTS (SELECT * FROM items)"
-    def exists(opts = nil)
-      LiteralString.new("EXISTS (#{select_sql(opts)})")
+    def exists(opts = (defarg=true;nil))
+      Deprecation.deprecate("Calling Dataset#exists with an argument is deprecated and will raise an error in Sequel 3.0.  Use dataset.clone(opts).exists.") unless defarg
+      LiteralString.new("EXISTS (#{defarg ? select_sql : select_sql(opts)})")
     end
 
     # Returns a copy of the dataset with the given conditions imposed upon it.  
-    # If the query has been grouped, then the conditions are imposed in the 
-    # HAVING clause. If not, then they are imposed in the WHERE clause. Filter
+    # If the query already has a HAVING clause, then the conditions are imposed in the 
+    # HAVING clause. If not, then they are imposed in the WHERE clause.
     # 
     # filter accepts the following argument types:
     #
-    # * Hash - list of equality expressions
+    # * Hash - list of equality/inclusion expressions
     # * Array - depends:
     #   * If first member is a string, assumes the rest of the arguments
     #     are parameters and interpolates them into the string.
@@ -148,10 +168,13 @@ module Sequel
     # * String - taken literally
     # * Symbol - taken as a boolean column argument (e.g. WHERE active)
     # * Sequel::SQL::BooleanExpression - an existing condition expression,
-    #   probably created using the Sequel blockless filter DSL.
+    #   probably created using the Sequel expression filter DSL.
     #
     # filter also takes a block, which should return one of the above argument
-    # types, and is treated the same way. If both a block and regular argument
+    # types, and is treated the same way.  This block yields a virtual row object,
+    # which is easy to use to create identifiers and functions.
+    #
+    # If both a block and regular argument
     # are provided, they get ANDed together.
     #
     # Examples:
@@ -177,14 +200,8 @@ module Sequel
     #
     # See doc/dataset_filters.rdoc for more examples and details.
     def filter(*cond, &block)
-      clause = (@opts[:having] ? :having : :where)
-      cond = cond.first if cond.size == 1
-      cond = transform_save(cond) if @transform if cond.is_a?(Hash)
-      cond = filter_expr(cond, &block)
-      cond = SQL::BooleanExpression.new(:AND, @opts[clause], cond) if @opts[clause] && !@opts[clause].blank?
-      clone(clause => cond)
+      _filter(@opts[:having] ? :having : :where, *cond, &block)
     end
-    alias_method :where, :filter
 
     # The first source (primary table) for this dataset.  If the dataset doesn't
     # have a table, raises an error.  If the table is aliased, returns the aliased name.
@@ -205,6 +222,9 @@ module Sequel
     end
 
     # Returns a copy of the dataset with the source changed.
+    #
+    #   dataset.from(:blah) # SQL: SELECT * FROM blah
+    #   dataset.from(:blah, :foo) # SQL: SELECT * FROM blah, foo
     def from(*source)
       clone(:from => source)
     end
@@ -232,22 +252,30 @@ module Sequel
     # in some databases).  See Sequel::SQL::StringExpression.like.  Note that the
     # total number of pattern matches will be cols.length * terms.length,
     # which could cause performance issues.
+    #
+    #   dataset.grep(:a, '%test%') # SQL: SELECT * FROM items WHERE a LIKE '%test%'
+    #   dataset.grep([:a, :b], %w'%test% foo') # SQL: SELECT * FROM items WHERE a LIKE '%test%' OR a LIKE 'foo' OR b LIKE '%test%' OR b LIKE 'foo' 
     def grep(cols, terms)
       filter(SQL::BooleanExpression.new(:OR, *Array(cols).collect{|c| SQL::StringExpression.like(c, *terms)}))
     end
 
     # Returns a copy of the dataset with the results grouped by the value of 
-    # the given columns
+    # the given columns.
+    #
+    #   dataset.group(:id) # SELECT * FROM items GROUP BY id
+    #   dataset.group(:id, :name) # SELECT * FROM items GROUP BY id, name
     def group(*columns)
       clone(:group => columns)
     end
-    alias_method :group_by, :group
+    alias group_by group
 
-    # Returns a copy of the dataset with the having conditions changed. Raises 
-    # an error if the dataset has not been grouped. See also #filter.
+    # Returns a copy of the dataset with the HAVING conditions changed. Raises 
+    # an error if the dataset has not been grouped. See #filter for argument types.
+    #
+    #   dataset.group(:sum).having(:sum=>10) # SQL: SELECT * FROM items GROUP BY sum HAVING sum = 10 
     def having(*cond, &block)
-      raise(Error::InvalidOperation, "Can only specify a HAVING clause on a grouped dataset") unless @opts[:group]
-      clone(:having=>{}).filter(*cond, &block)
+      raise(InvalidOperation, "Can only specify a HAVING clause on a grouped dataset") unless @opts[:group]
+      _filter(:having, *cond, &block)
     end
     
     # Inserts multiple values. If a block is given it is invoked for each
@@ -266,7 +294,7 @@ module Sequel
     # the resulting statement includes column names. If no values are given, 
     # the resulting statement includes a DEFAULT VALUES clause.
     #
-    #   dataset.insert_sql() #=> 'INSERT INTO items DEFAULT VALUES'
+    #   dataset.insert_sql #=> 'INSERT INTO items DEFAULT VALUES'
     #   dataset.insert_sql(1,2,3) #=> 'INSERT INTO items VALUES (1, 2, 3)'
     #   dataset.insert_sql(:a => 1, :b => 2) #=>
     #     'INSERT INTO items (a, b) VALUES (1, 2)'
@@ -279,7 +307,7 @@ module Sequel
         values = {}
       when 1
         vals = values.at(0)
-        if vals.is_one_of?(Hash, Dataset, Array)
+        if [Hash, Dataset, Array].any?{|c| vals.is_a?(c)}
           values = vals
         elsif vals.respond_to?(:values)
           values = vals.values
@@ -360,7 +388,7 @@ module Sequel
 
     # Returns a joined dataset.  Uses the following arguments:
     #
-    # * type - The type of join to do (:inner, :left_outer, :right_outer, :full)
+    # * type - The type of join to do (e.g. :inner)
     # * table - Depends on type:
     #   * Dataset - a subselect is performed with an alias of tN for some value of N
     #   * Model (or anything responding to :table_name) - table.table_name
@@ -389,7 +417,7 @@ module Sequel
     #   the table alias/name for the last joined (or first table), and an array of previous
     #   SQL::JoinClause.
     def join_table(type, table, expr=nil, options={}, &block)
-      if options.is_one_of?(Symbol, String)
+      if [Symbol, String].any?{|c| options.is_a?(c)}
         table_alias = options
         last_alias = nil 
       else
@@ -414,7 +442,7 @@ module Sequel
         SQL::JoinUsingClause.new(expr, type, table, table_alias)
       else
         last_alias ||= @opts[:last_joined_table] || (first_source.is_a?(Dataset) ? 't1' : first_source)
-        if Hash === expr or (Array === expr and expr.all_two_pairs?)
+        if Sequel.condition_specifier?(expr)
           expr = expr.collect do |k, v|
             k = qualified_column_name(k, table_name) if k.is_a?(Symbol)
             v = qualified_column_name(v, last_alias) if v.is_a?(Symbol)
@@ -436,12 +464,15 @@ module Sequel
     # If given an integer, the dataset will contain only the first l results.
     # If given a range, it will contain only those at offsets within that
     # range. If a second argument is given, it is used as an offset.
+    #
+    #   dataset.limit(10) # SQL: SELECT * FROM items LIMIT 10
+    #   dataset.limit(10, 20) # SQL: SELECT * FROM items LIMIT 10 OFFSET 20
     def limit(l, o = nil)
       return from_self.limit(l, o) if @opts[:sql]
 
       if Range === l
         o = l.first
-        l = l.interval + 1
+        l = l.last - l.first + (l.exclude_end? ? 0 : 1)
       end
       l = l.to_i
       raise(Error, 'Limits must be greater than or equal to 1') unless l >= 1
@@ -509,28 +540,25 @@ module Sequel
     # This method should be overridden by descendants if the support
     # inserting multiple records in a single SQL statement.
     def multi_insert_sql(columns, values)
-      table = quote_identifier(@opts[:from].first)
-      columns = identifier_list(columns)
-      values.map do |r|
-        "INSERT INTO #{table} (#{columns}) VALUES #{literal(r)}"
-      end
+      s = "INSERT INTO #{source_list(@opts[:from])} (#{identifier_list(columns)}) VALUES "
+      values.map{|r| s + literal(r)}
     end
     
     # Adds an alternate filter to an existing filter using OR. If no filter 
     # exists an error is raised.
+    #
+    #   dataset.filter(:a).or(:b) # SQL: SELECT * FROM items WHERE a OR b
     def or(*cond, &block)
       clause = (@opts[:having] ? :having : :where)
+      raise(InvalidOperation, "No existing filter found.") unless @opts[clause]
       cond = cond.first if cond.size == 1
-      if @opts[clause]
-        clone(clause => SQL::BooleanExpression.new(:OR, @opts[clause], filter_expr(cond, &block)))
-      else
-        raise Error::NoExistingFilter, "No existing filter found."
-      end
+      clone(clause => SQL::BooleanExpression.new(:OR, @opts[clause], filter_expr(cond, &block)))
     end
 
     # Returns a copy of the dataset with the order changed. If a nil is given
     # the returned dataset has no order. This can accept multiple arguments
-    # of varying kinds, and even SQL functions.
+    # of varying kinds, and even SQL functions.  If a block is given, it is treated
+    # as a virtual row block, similar to filter.
     #
     #   ds.order(:name).sql #=> 'SELECT * FROM items ORDER BY name'
     #   ds.order(:a, :b).sql #=> 'SELECT * FROM items ORDER BY a, b'
@@ -538,19 +566,21 @@ module Sequel
     #   ds.order(:a + :b).sql #=> 'SELECT * FROM items ORDER BY (a + b)'
     #   ds.order(:name.desc).sql #=> 'SELECT * FROM items ORDER BY name DESC'
     #   ds.order(:name.asc).sql #=> 'SELECT * FROM items ORDER BY name ASC'
-    #   ds.order(:arr|1).sql #=> 'SELECT * FROM items ORDER BY arr[1]'
+    #   ds.order{|o| o.sum(:name)}.sql #=> 'SELECT * FROM items ORDER BY sum(name)'
     #   ds.order(nil).sql #=> 'SELECT * FROM items'
-    def order(*columns)
-      columns += Array((yield SQL::VirtualRow.new)) if block_given?
+    def order(*columns, &block)
+      columns += Array(virtual_row_block_call(block)) if block
       clone(:order => (columns.compact.empty?) ? nil : columns)
     end
     alias_method :order_by, :order
     
     # Returns a copy of the dataset with the order columns added
     # to the existing order.
-    def order_more(*columns)
-      columns += Array((yield SQL::VirtualRow.new)) if block_given?
-      order(*((@opts[:order] || []) + columns))
+    #
+    #   ds.order(:a).order(:b).sql #=> 'SELECT * FROM items ORDER BY b'
+    #   ds.order(:a).order_more(:b).sql #=> 'SELECT * FROM items ORDER BY a, b'
+    def order_more(*columns, &block)
+      order(*Array(@opts[:order]).concat(columns), &block)
     end
     
     # SQL fragment for the ordered expression, used in the ORDER BY
@@ -570,7 +600,7 @@ module Sequel
     # SQL fragment for the qualifed identifier, specifying
     # a table and a column (or schema and table).
     def qualified_identifier_sql(qcr)
-      [qcr.table, qcr.column].map{|x| x.is_one_of?(SQL::QualifiedIdentifier, SQL::Identifier, Symbol) ? literal(x) : quote_identifier(x)}.join('.')
+      [qcr.table, qcr.column].map{|x| [SQL::QualifiedIdentifier, SQL::Identifier, Symbol].any?{|c| x.is_a?(c)} ? literal(x) : quote_identifier(x)}.join('.')
     end
 
     # Adds quoting to identifiers (columns and tables). If identifiers are not
@@ -582,7 +612,6 @@ module Sequel
       name = quoted_identifier(name) if quote_identifiers?
       name
     end
-    alias_method :quote_column_ref, :quote_identifier
 
     # Separates the schema from the table and returns a string with them
     # quoted (if quoting identifiers)
@@ -603,7 +632,7 @@ module Sequel
     def reverse_order(*order)
       order(*invert_order(order.empty? ? @opts[:order] : order))
     end
-    alias_method :reverse, :reverse_order
+    alias reverse reverse_order
 
     # Split the schema information from the table
     def schema_and_table(table_name)
@@ -624,27 +653,38 @@ module Sequel
     end
 
     # Returns a copy of the dataset with the columns selected changed
-    # to the given columns.
-    def select(*columns)
-      columns += Array((yield SQL::VirtualRow.new)) if block_given?
+    # to the given columns. This also takes a virtual row block,
+    # similar to filter.
+    #
+    #   dataset.select(:a) # SELECT a FROM items
+    #   dataset.select(:a, :b) # SELECT a, b FROM items
+    #   dataset.select{|o| o.a, o.sum(:b)} # SELECT a, sum(b) FROM items
+    def select(*columns, &block)
+      columns += Array(virtual_row_block_call(block)) if block
       clone(:select => columns)
     end
     
     # Returns a copy of the dataset selecting the wildcard.
+    #
+    #   dataset.select(:a).select_all # SELECT * FROM items
     def select_all
       clone(:select => nil)
     end
 
     # Returns a copy of the dataset with the given columns added
     # to the existing selected columns.
-    def select_more(*columns)
-      columns += Array((yield SQL::VirtualRow.new)) if block_given?
-      select(*((@opts[:select] || []) + columns))
+    #
+    #   dataset.select(:a).select(:b) # SELECT b FROM items
+    #   dataset.select(:a).select_more(:b) # SELECT a, b FROM items
+    def select_more(*columns, &block)
+      select(*Array(@opts[:select]).concat(columns), &block)
     end
     
-    # Formats a SELECT statement using the given options and the dataset
-    # options.
-    def select_sql(opts = nil)
+    # Formats a SELECT statement
+    #
+    #   dataset.select_sql # => "SELECT * FROM items"
+    def select_sql(opts = (defarg=true;nil))
+      Deprecation.deprecate("Calling Dataset#select_sql with an argument is deprecated and will raise an error in Sequel 3.0.  Use dataset.clone(opts).select_sql.") unless defarg
       opts = opts ? @opts.merge(opts) : @opts
       return static_sql(opts[:sql]) if opts[:sql]
       sql = 'SELECT'
@@ -653,8 +693,9 @@ module Sequel
     end
 
     # Same as select_sql, not aliased directly to make subclassing simpler.
-    def sql(*args)
-      select_sql(*args)
+    def sql(opts = (defarg=true;nil))
+      Deprecation.deprecate("Calling Dataset#select_sql with an argument is deprecated and will raise an error in Sequel 3.0.  Use dataset.clone(opts).select_sql.") unless defarg
+      defarg ? select_sql : select_sql(opts)
     end
 
     # SQL fragment for specifying subscripts (SQL arrays)
@@ -662,21 +703,9 @@ module Sequel
       "#{s.f}[#{s.sub.join(COMMA_SEPARATOR)}]"
     end
 
-    # Converts a symbol into a column name. This method supports underscore
-    # notation in order to express qualified (two underscores) and aliased
-    # (three underscores) columns:
-    #
-    #   ds = DB[:items]
-    #   :abc.to_column_ref(ds) #=> "abc"
-    #   :abc___a.to_column_ref(ds) #=> "abc AS a"
-    #   :items__abc.to_column_ref(ds) #=> "items.abc"
-    #   :items__abc___a.to_column_ref(ds) #=> "items.abc AS a"
-    #
-    def symbol_to_column_ref(sym)
-      literal_symbol(sym)
-    end
-
     # Returns a copy of the dataset with no filters (HAVING or WHERE clause) applied.
+    # 
+    #   dataset.group(:a).having(:a=>1).where(:b).unfiltered # SELECT * FROM items
     def unfiltered
       clone(:where => nil, :having => nil)
     end
@@ -690,13 +719,9 @@ module Sequel
       compound_clone(:union, dataset, all)
     end
 
-    # Returns a copy of the dataset with the distinct option.
-    def uniq(*args)
-      clone(:distinct => args)
-    end
-    alias_method :distinct, :uniq
-
     # Returns a copy of the dataset with no order.
+    # 
+    #   dataset.order(:a).unordered # SELECT * FROM items
     def unordered
       order(nil)
     end
@@ -706,19 +731,18 @@ module Sequel
     #   dataset.update_sql(:price => 100, :category => 'software') #=>
     #     "UPDATE items SET price = 100, category = 'software'"
     #
-    # Accepts a block, but such usage is discouraged.
-    #
     # Raises an error if the dataset is grouped or includes more
     # than one table.
-    def update_sql(values = {}, opts = nil)
+    def update_sql(values = {}, opts = (defarg=true;nil))
+      Deprecation.deprecate("Calling Dataset#update_sql with an argument is deprecated and will raise an error in Sequel 3.0.  Use dataset.clone(opts).update_sql.") unless defarg
       opts = opts ? @opts.merge(opts) : @opts
 
       return static_sql(opts[:sql]) if opts[:sql]
 
       if opts[:group]
-        raise Error::InvalidOperation, "A grouped dataset cannot be updated"
+        raise InvalidOperation, "A grouped dataset cannot be updated"
       elsif (opts[:from].size > 1) or opts[:join]
-        raise Error::InvalidOperation, "A joined dataset cannot be updated"
+        raise InvalidOperation, "A joined dataset cannot be updated"
       end
       
       sql = "UPDATE #{source_list(@opts[:from])} SET "
@@ -728,7 +752,7 @@ module Sequel
         # get values from hash
         values = transform_save(values) if @transform
         values.map do |k, v|
-          "#{k.is_one_of?(String, Symbol) ? quote_identifier(k) : literal(k)} = #{literal(v)}"
+          "#{[String, Symbol].any?{|c| k.is_a?(c)} ? quote_identifier(k) : literal(k)} = #{literal(v)}"
         end.join(COMMA_SEPARATOR)
       else
         # copy values verbatim
@@ -742,16 +766,27 @@ module Sequel
       sql
     end
 
+    # Add a condition to the WHERE clause.  See #filter for argument types.
+    #
+    #   dataset.group(:a).having(:a).filter(:b) # SELECT * FROM items GROUP BY a HAVING a AND b
+    #   dataset.group(:a).having(:a).where(:b) # SELECT * FROM items WHERE b GROUP BY a HAVING a
+    def where(*cond, &block)
+      _filter(:where, *cond, &block)
+    end
+
     # Returns a copy of the dataset with the static SQL used.  This is useful if you want
     # to keep the same row_proc/transform/graph, but change the SQL used to custom SQL.
-    def with_sql(sql)
+    #
+    #   dataset.with_sql('SELECT * FROM foo') # SELECT * FROM foo
+    def with_sql(sql, *args)
+      sql = SQL::PlaceholderLiteralString.new(sql, args) unless args.empty?
       clone(:sql=>sql)
     end
 
     [:inner, :full_outer, :right_outer, :left_outer].each do |jtype|
       class_eval("def #{jtype}_join(*args, &block); join_table(:#{jtype}, *args, &block) end")
     end
-    alias_method :join, :inner_join
+    alias join inner_join
 
     protected
 
@@ -764,6 +799,15 @@ module Sequel
 
     private
 
+    # Internal filter method so it works on either the having or where clauses.
+    def _filter(clause, *cond, &block)
+      cond = cond.first if cond.size == 1
+      cond = transform_save(cond) if @transform if cond.is_a?(Hash)
+      cond = filter_expr(cond, &block)
+      cond = SQL::BooleanExpression.new(:AND, @opts[clause], cond) if @opts[clause]
+      clone(clause => cond)
+    end
+
     # SQL fragment for specifying an alias.  expression should already be literalized.
     def as_sql(expression, aliaz)
       "#{expression} AS #{quote_identifier(aliaz)}"
@@ -772,7 +816,7 @@ module Sequel
     # Converts an array of column names into a comma seperated string of 
     # column names. If the array is empty, a wildcard (*) is returned.
     def column_list(columns)
-      if columns.blank?
+      if columns.nil? || columns.empty?
         WILDCARD
       else
         m = columns.map do |i|
@@ -811,7 +855,7 @@ module Sequel
           SQL::BooleanExpression.from_value_pairs(expr)
         end
       when Proc
-        filter_expr(expr.call(SQL::VirtualRow.new))
+        filter_expr(virtual_row_block_call(expr))
       when SQL::NumericExpression, SQL::StringExpression
         raise(Error, "Invalid SQL Expression type: #{expr.inspect}") 
       when Symbol, SQL::Expression
@@ -862,7 +906,7 @@ module Sequel
 
     # SQL fragment for Array.  Treats as an expression if an array of all two pairs, or as a SQL array otherwise.
     def literal_array(v)
-      v.all_two_pairs? ? literal_expression(v.sql_expr) : array_sql(v)
+      Sequel.condition_specifier?(v) ? literal_expression(SQL::BooleanExpression.from_value_pairs(v)) : array_sql(v)
     end
 
     # SQL fragment for BigDecimal
@@ -908,7 +952,7 @@ module Sequel
 
     # SQL fragment for Hash, treated as an expression
     def literal_hash(v)
-      literal_expression(v.sql_expr)
+      literal_expression(SQL::BooleanExpression.from_value_pairs(v))
     end
 
     # SQL fragment for Integer
@@ -926,7 +970,14 @@ module Sequel
       "'#{v.gsub(/\\/, "\\\\\\\\").gsub(/'/, "''")}'"
     end
 
-    # SQL fragment for Symbol, treated as an identifier, possibly aliased and/or qualified.
+    # Converts a symbol into a column name. This method supports underscore
+    # notation in order to express qualified (two underscores) and aliased
+    # (three underscores) columns:
+    #
+    #   dataset.literal(:abc) #=> "abc"
+    #   dataset.literal(:abc___a) #=> "abc AS a"
+    #   dataset.literal(:items__abc) #=> "items.abc"
+    #   dataset.literal(:items__abc___a) #=> "items.abc AS a"
     def literal_symbol(v)
       c_table, column, c_alias = split_symbol(v)
       qc = "#{"#{quote_identifier(c_table)}." if c_table}#{quote_identifier(column)}"
@@ -1080,12 +1131,12 @@ module Sequel
     # SQL fragment specifying a table name.
     def table_ref(t)
       case t
+      when Symbol
+        literal_symbol(t)
       when Dataset
         t.to_table_reference
       when Hash
         t.map{|k, v| as_sql(table_ref(k), v)}.join(COMMA_SEPARATOR)
-      when Symbol
-        symbol_to_column_ref(t)
       when String
         quote_identifier(t)
       else