viking-sequel 3.10.0

data/lib/sequel/dataset/mutation.rb

@@ -0,0 +1,64 @@
+module Sequel
+  class Dataset
+    # ---------------------
+    # :section: Mutation methods
+    # These methods modify the receiving dataset and should be used with care.
+    # ---------------------
+    
+    # All methods that should have a ! method added that modifies
+    # the receiver.
+    MUTATION_METHODS = %w'add_graph_aliases and cross_join distinct except exclude
+    filter for_update from from_self full_join full_outer_join graph
+    group group_and_count group_by having inner_join intersect invert join join_table left_join
+    left_outer_join limit lock_style naked natural_full_join natural_join
+    natural_left_join natural_right_join or order order_by order_more paginate qualify query
+    reverse reverse_order right_join right_outer_join select select_all select_append select_more server
+    set_defaults set_graph_aliases set_overrides unfiltered ungraphed ungrouped union
+    unlimited unordered where with with_recursive with_sql'.collect{|x| x.to_sym}
+    
+    # Setup mutation (e.g. filter!) methods.  These operate the same as the
+    # non-! methods, but replace the options of the current dataset with the
+    # options of the resulting dataset.
+    def self.def_mutation_method(*meths)
+      meths.each do |meth|
+        class_eval("def #{meth}!(*args, &block); mutation_method(:#{meth}, *args, &block) end", __FILE__, __LINE__)
+      end
+    end
+    
+    # Add the mutation methods via metaprogramming
+    def_mutation_method(*MUTATION_METHODS)
+    
+    
+    # Set the method to call on identifiers going into the database for this dataset
+    attr_accessor :identifier_input_method
+    
+    # Set the method to call on identifiers coming the database for this dataset
+    attr_accessor :identifier_output_method
+
+    # Whether to quote identifiers for this dataset
+    attr_writer :quote_identifiers
+    
+    # The row_proc for this database, should be a Proc that takes
+    # a single hash argument and returns the object you want
+    # each to return.
+    attr_accessor :row_proc
+    
+    # Add a mutation method to this dataset instance.
+    def def_mutation_method(*meths)
+      meths.each do |meth|
+        instance_eval("def #{meth}!(*args, &block); mutation_method(:#{meth}, *args, &block) end", __FILE__, __LINE__)
+      end
+    end
+    
+    private
+    
+    # Modify the receiver with the results of sending the meth, args, and block
+    # to the receiver and merging the options of the resulting dataset into
+    # the receiver's options.
+    def mutation_method(meth, *args, &block)
+      copy = send(meth, *args, &block)
+      @opts.merge!(copy.opts)
+      self
+    end
+  end
+end

data/lib/sequel/dataset/prepared_statements.rb

@@ -0,0 +1,227 @@
+module Sequel 
+  class Dataset
+    # ---------------------
+    # :section: Methods related to prepared statements or bound variables
+    # On some adapters, these use native prepared statements and bound variables, on others
+    # support is emulated.  For details, see the {"Prepared Statements/Bound Variables" guide}[link:files/doc/prepared_statements_rdoc.html].
+    # ---------------------
+    
+    PREPARED_ARG_PLACEHOLDER = LiteralString.new('?').freeze
+    
+    # Default implementation of the argument mapper to allow
+    # native database support for bind variables and prepared
+    # statements (as opposed to the emulated ones used by default).
+    module ArgumentMapper
+      SQL_QUERY_TYPE = Hash.new{|h,k| h[k] = k}
+      SQL_QUERY_TYPE[:first] = SQL_QUERY_TYPE[:all] = :select
+      
+      # The name of the prepared statement, if any.
+      attr_accessor :prepared_statement_name
+      
+      # The bind arguments to use for running this prepared statement
+      attr_accessor :bind_arguments
+      
+      # Set the bind arguments based on the hash and call super.
+      def call(bind_vars={}, &block)
+        ds = bind(bind_vars)
+        ds.prepared_sql
+        ds.bind_arguments = ds.map_to_prepared_args(ds.opts[:bind_vars])
+        ds.run(&block)
+      end
+        
+      # Override the given *_sql method based on the type, and
+      # cache the result of the sql.
+      def prepared_sql
+        return @prepared_sql if @prepared_sql
+        @prepared_args ||= []
+        @prepared_sql = super
+        meta_def("#{sql_query_type}_sql"){|*args| prepared_sql}
+        @prepared_sql
+      end
+      
+      private
+      
+      # The type of query (:select, :insert, :delete, :update).
+      def sql_query_type
+        SQL_QUERY_TYPE[@prepared_type]
+      end
+    end
+
+    # Backbone of the prepared statement support.  Grafts bind variable
+    # support into datasets by hijacking #literal and using placeholders.
+    # By default, emulates prepared statements and bind variables by
+    # taking the hash of bind variables and directly substituting them
+    # into the query, which works on all databases, as it is no different
+    # from using the dataset without bind variables.
+    module PreparedStatementMethods
+      PLACEHOLDER_RE = /\A\$(.*)\z/
+      
+      # The type of prepared statement, should be one of :select, :first,
+      # :insert, :update, or :delete
+      attr_accessor :prepared_type
+      
+      # The array/hash of bound variable placeholder names.
+      attr_accessor :prepared_args
+      
+      # The argument to supply to insert and update, which may use
+      # placeholders specified by prepared_args
+      attr_accessor :prepared_modify_values
+      
+      # Sets the prepared_args to the given hash and runs the
+      # prepared statement.
+      def call(bind_vars={}, &block)
+        bind(bind_vars).run(&block)
+      end
+      
+      # Returns the SQL for the prepared statement, depending on
+      # the type of the statement and the prepared_modify_values.
+      def prepared_sql
+        case @prepared_type
+        when :select, :all
+          select_sql
+        when :first
+          clone(:limit=>1).select_sql
+        when :insert
+          insert_sql(*@prepared_modify_values)
+        when :update
+          update_sql(*@prepared_modify_values)
+        when :delete
+          delete_sql
+        end
+      end
+      
+      # Changes the values of symbols if they start with $ and
+      # prepared_args is present.  If so, they are considered placeholders,
+      # and they are substituted using prepared_arg.
+      def literal_symbol(v)
+        if @opts[:bind_vars] and match = PLACEHOLDER_RE.match(v.to_s)
+          v2 = prepared_arg(match[1].to_sym)
+          v2 ? literal(v2) : v
+        else
+          super
+        end
+      end
+      
+      # Programmer friendly string showing this is a prepared statement,
+      # with the prepared SQL it represents (which in general won't have
+      # substituted variables).
+      def inspect
+        "<#{self.class.name}/PreparedStatement #{prepared_sql.inspect}>"
+      end
+      
+      protected
+      
+      # Run the method based on the type of prepared statement, with
+      # :select running #all to get all of the rows, and the other
+      # types running the method with the same name as the type.
+      def run(&block)
+        case @prepared_type
+        when :select, :all
+          all(&block)
+        when :first
+          first
+        when :insert
+          insert(*@prepared_modify_values)
+        when :update
+          update(*@prepared_modify_values)
+        when :delete
+          delete
+        end
+      end
+      
+      private
+      
+      # Returns the value of the prepared_args hash for the given key.
+      def prepared_arg(k)
+        @opts[:bind_vars][k]
+      end
+
+      # Use a clone of the dataset extended with prepared statement
+      # support and using the same argument hash so that you can use
+      # bind variables/prepared arguments in subselects.
+      def subselect_sql(ds)
+        ps = ds.prepare(:select)
+        ps = ps.bind(@opts[:bind_vars]) if @opts[:bind_vars]
+        ps.prepared_args = prepared_args
+        ps.prepared_sql
+      end
+    end
+    
+    # Default implementation for an argument mapper that uses
+    # unnumbered SQL placeholder arguments.  Keeps track of which
+    # arguments have been used, and allows arguments to
+    # be used more than once.
+    module UnnumberedArgumentMapper
+      include ArgumentMapper
+      
+      protected
+      
+      # Returns a single output array mapping the values of the input hash.
+      # Keys in the input hash that are used more than once in the query
+      # have multiple entries in the output array.
+      def map_to_prepared_args(bind_vars)
+        prepared_args.map{|v| bind_vars[v]}
+      end
+      
+      private
+      
+      # Associates the argument with name k with the next position in
+      # the output array.
+      def prepared_arg(k)
+        prepared_args << k
+        prepared_arg_placeholder
+      end
+    end
+    
+    # Set the bind variables to use for the call.  If bind variables have
+    # already been set for this dataset, they are updated with the contents
+    # of bind_vars.
+    def bind(bind_vars={})
+      clone(:bind_vars=>@opts[:bind_vars] ? @opts[:bind_vars].merge(bind_vars) : bind_vars)
+    end
+    
+    # For the given type (:select, :insert, :update, or :delete),
+    # run the sql with the bind variables
+    # specified in the hash.  values is a hash of passed to
+    # insert or update (if one of those types is used),
+    # which may contain placeholders.
+    def call(type, bind_variables={}, *values, &block)
+      prepare(type, nil, *values).call(bind_variables, &block)
+    end
+    
+    # Prepare an SQL statement for later execution. This returns
+    # a clone of the dataset extended with PreparedStatementMethods,
+    # on which you can call call with the hash of bind variables to
+    # do substitution.  The prepared statement is also stored in
+    # the associated database.  The following usage is identical:
+    #
+    #   ps = prepare(:select, :select_by_name)
+    #   ps.call(:name=>'Blah')
+    #   db.call(:select_by_name, :name=>'Blah')
+    def prepare(type, name=nil, *values)
+      ps = to_prepared_statement(type, values)
+      db.prepared_statements[name] = ps if name
+      ps
+    end
+    
+    protected
+    
+    # Return a cloned copy of the current dataset extended with
+    # PreparedStatementMethods, setting the type and modify values.
+    def to_prepared_statement(type, values=nil)
+      ps = bind
+      ps.extend(PreparedStatementMethods)
+      ps.prepared_type = type
+      ps.prepared_modify_values = values
+      ps
+    end
+
+    private
+    
+    # The argument placeholder.  Most databases used unnumbered
+    # arguments with question marks, so that is the default.
+    def prepared_arg_placeholder
+      PREPARED_ARG_PLACEHOLDER
+    end
+  end
+end

data/lib/sequel/dataset/query.rb

@@ -0,0 +1,709 @@
+module Sequel
+  class Dataset
+    # ---------------------
+    # :section: Methods that return modified datasets
+    # These methods all return modified copies of the receiver.
+    # ---------------------
+    # The dataset options that require the removal of cached columns
+    # if changed.
+    COLUMN_CHANGE_OPTS = [:select, :sql, :from, :join].freeze
+
+    # Which options don't affect the SQL generation.  Used by simple_select_all?
+    # to determine if this is a simple SELECT * FROM table.
+    NON_SQL_OPTIONS = [:server, :defaults, :overrides, :graph, :eager_graph, :graph_aliases]
+    
+    # These symbols have _join methods created (e.g. inner_join) that
+    # call join_table with the symbol, passing along the arguments and
+    # block from the method call.
+    CONDITIONED_JOIN_TYPES = [:inner, :full_outer, :right_outer, :left_outer, :full, :right, :left]
+
+    # These symbols have _join methods created (e.g. natural_join) that
+    # call join_table with the symbol.  They only accept a single table
+    # argument which is passed to join_table, and they raise an error
+    # if called with a block.
+    UNCONDITIONED_JOIN_TYPES = [:natural, :natural_left, :natural_right, :natural_full, :cross]
+    
+    # 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(InvalidOperation, "No existing filter found.") unless @opts[:having] || @opts[:where]
+      filter(*cond, &block)
+    end
+    
+    # Returns a new clone of the dataset with with the given options merged.
+    # If the options changed include options in COLUMN_CHANGE_OPTS, the cached
+    # columns are deleted.
+    def clone(opts = {})
+      c = super()
+      c.opts = @opts.merge(opts)
+      c.instance_variable_set(:@columns, nil) if opts.keys.any?{|o| COLUMN_CHANGE_OPTS.include?(o)}
+      c
+    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.  Raises an error if arguments
+    # are given and DISTINCT ON is not supported.
+    #
+    #  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)
+      raise(InvalidOperation, "DISTINCT ON not supported") if !args.empty? && !supports_distinct_on?
+      clone(:distinct => args)
+    end
+
+    # Adds an EXCEPT clause using a second dataset object.
+    # An EXCEPT compound dataset returns all rows in the current dataset
+    # that are not in the given dataset.
+    # Raises an InvalidOperation if the operation is not supported.
+    # Options:
+    # * :all - Set to true to use EXCEPT ALL instead of EXCEPT, so duplicate rows can occur
+    # * :from_self - Set to false to not wrap the returned dataset in a from_self, use with care.
+    #
+    #   DB[:items].except(DB[:other_items]).sql
+    #   #=> "SELECT * FROM items EXCEPT SELECT * FROM other_items"
+    def except(dataset, opts={})
+      opts = {:all=>opts} unless opts.is_a?(Hash)
+      raise(InvalidOperation, "EXCEPT not supported") unless supports_intersect_except?
+      raise(InvalidOperation, "EXCEPT ALL not supported") if opts[:all] && !supports_intersect_except_all?
+      compound_clone(:except, dataset, opts)
+    end
+
+    # Performs the inverse of Dataset#filter.
+    #
+    #   dataset.exclude(:category => 'software').sql #=>
+    #     "SELECT * FROM items WHERE (category != 'software')"
+    def exclude(*cond, &block)
+      clause = (@opts[:having] ? :having : :where)
+      cond = cond.first if cond.size == 1
+      cond = filter_expr(cond, &block)
+      cond = SQL::BooleanExpression.invert(cond)
+      cond = SQL::BooleanExpression.new(:AND, @opts[clause], cond) if @opts[clause]
+      clone(clause => cond)
+    end
+
+    # Returns a copy of the dataset with the given conditions imposed upon it.  
+    # 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/inclusion expressions
+    # * Array - depends:
+    #   * If first member is a string, assumes the rest of the arguments
+    #     are parameters and interpolates them into the string.
+    #   * If all members are arrays of length two, treats the same way
+    #     as a hash, except it allows for duplicate keys to be
+    #     specified.
+    # * 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 expression filter DSL.
+    #
+    # filter also takes a block, which should return one of the above 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.  For more details
+    # on the virtual row support, see the {"Virtual Rows" guide}[link:files/doc/virtual_rows_rdoc.html]
+    #
+    # If both a block and regular argument
+    # are provided, they get ANDed together.
+    #
+    # Examples:
+    #
+    #   dataset.filter(:id => 3).sql #=>
+    #     "SELECT * FROM items WHERE (id = 3)"
+    #   dataset.filter('price < ?', 100).sql #=>
+    #     "SELECT * FROM items WHERE price < 100"
+    #   dataset.filter([[:id, (1,2,3)], [:id, 0..10]]).sql #=>
+    #     "SELECT * FROM items WHERE ((id IN (1, 2, 3)) AND ((id >= 0) AND (id <= 10)))"
+    #   dataset.filter('price < 100').sql #=>
+    #     "SELECT * FROM items WHERE price < 100"
+    #   dataset.filter(:active).sql #=>
+    #     "SELECT * FROM items WHERE :active
+    #   dataset.filter{|o| o.price < 100}.sql #=>
+    #     "SELECT * FROM items WHERE (price < 100)"
+    # 
+    # Multiple filter calls can be chained for scoping:
+    #
+    #   software = dataset.filter(:category => 'software')
+    #   software.filter{|o| o.price < 100}.sql #=>
+    #     "SELECT * FROM items WHERE ((category = 'software') AND (price < 100))"
+    #
+    # See the the {"Dataset Filtering" guide}[link:files/doc/dataset_filtering_rdoc.html] for more examples and details.
+    def filter(*cond, &block)
+      _filter(@opts[:having] ? :having : :where, *cond, &block)
+    end
+    
+    # Returns a cloned dataset with a :update lock style.
+    def for_update
+      lock_style(:update)
+    end
+
+    # Returns a copy of the dataset with the source changed.
+    #
+    #   dataset.from # SQL: SELECT *
+    #   dataset.from(:blah) # SQL: SELECT * FROM blah
+    #   dataset.from(:blah, :foo) # SQL: SELECT * FROM blah, foo
+    def from(*source)
+      table_alias_num = 0
+      sources = []
+      source.each do |s|
+        case s
+        when Hash
+          s.each{|k,v| sources << SQL::AliasedExpression.new(k,v)}
+        when Dataset
+          sources << SQL::AliasedExpression.new(s, dataset_alias(table_alias_num+=1))
+        when Symbol
+          sch, table, aliaz = split_symbol(s)
+          if aliaz
+            s = sch ? SQL::QualifiedIdentifier.new(sch.to_sym, table.to_sym) : SQL::Identifier.new(table.to_sym)
+            sources << SQL::AliasedExpression.new(s, aliaz.to_sym)
+          else
+            sources << s
+          end
+        else
+          sources << s
+        end
+      end
+      o = {:from=>sources.empty? ? nil : sources}
+      o[:num_dataset_sources] = table_alias_num if table_alias_num > 0
+      clone(o)
+    end
+
+    # Returns a dataset selecting from the current dataset.
+    # Supplying the :alias option controls the name of the result.
+    #
+    #   ds = DB[:items].order(:name).select(:id, :name)
+    #   ds.sql                         #=> "SELECT id,name FROM items ORDER BY name"
+    #   ds.from_self.sql               #=> "SELECT * FROM (SELECT id, name FROM items ORDER BY name) AS t1"
+    #   ds.from_self(:alias=>:foo).sql #=> "SELECT * FROM (SELECT id, name FROM items ORDER BY name) AS foo"
+    def from_self(opts={})
+      fs = {}
+      @opts.keys.each{|k| fs[k] = nil unless NON_SQL_OPTIONS.include?(k)}
+      clone(fs).from(opts[:alias] ? as(opts[:alias]) : self)
+    end
+
+    # Pattern match any of the columns to any of the terms.  The terms can be
+    # strings (which use LIKE) or regular expressions (which are only supported
+    # 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.
+    #
+    #   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.compact.empty? ? nil : columns))
+    end
+    alias group_by group
+    
+    # Returns a dataset grouped by the given column with count by group,
+    # order by the count of records. Column aliases may be supplied, and will
+    # be included in the select clause.
+    #
+    # Examples:
+    #
+    #   ds.group_and_count(:name).all => [{:name=>'a', :count=>1}, ...]
+    #   ds.group_and_count(:first_name, :last_name).all => [{:first_name=>'a', :last_name=>'b', :count=>1}, ...]
+    #   ds.group_and_count(:first_name___name).all => [{:name=>'a', :count=>1}, ...]
+    def group_and_count(*columns)
+      group(*columns.map{|c| unaliased_identifier(c)}).select(*(columns + [COUNT_OF_ALL_AS_COUNT]))
+    end
+
+    # Returns a copy of the dataset with the HAVING conditions changed. 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)
+      _filter(:having, *cond, &block)
+    end
+    
+    # Adds an INTERSECT clause using a second dataset object.
+    # An INTERSECT compound dataset returns all rows in both the current dataset
+    # and the given dataset.
+    # Raises an InvalidOperation if the operation is not supported.
+    # Options:
+    # * :all - Set to true to use INTERSECT ALL instead of INTERSECT, so duplicate rows can occur
+    # * :from_self - Set to false to not wrap the returned dataset in a from_self, use with care.
+    #
+    #   DB[:items].intersect(DB[:other_items]).sql
+    #   #=> "SELECT * FROM items INTERSECT SELECT * FROM other_items"
+    def intersect(dataset, opts={})
+      opts = {:all=>opts} unless opts.is_a?(Hash)
+      raise(InvalidOperation, "INTERSECT not supported") unless supports_intersect_except?
+      raise(InvalidOperation, "INTERSECT ALL not supported") if opts[:all] && !supports_intersect_except_all?
+      compound_clone(:intersect, dataset, opts)
+    end
+
+    # Inverts the current filter
+    #
+    #   dataset.filter(:category => 'software').invert.sql #=>
+    #     "SELECT * FROM items WHERE (category != 'software')"
+    def invert
+      having, where = @opts[:having], @opts[:where]
+      raise(Error, "No current filter") unless having || where
+      o = {}
+      o[:having] = SQL::BooleanExpression.invert(having) if having
+      o[:where] = SQL::BooleanExpression.invert(where) if where
+      clone(o)
+    end
+
+    # Returns a joined dataset.  Uses the following arguments:
+    #
+    # * 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
+    #   * String, Symbol: table
+    # * expr - specifies conditions, depends on type:
+    #   * Hash, Array with all two pairs - Assumes key (1st arg) is column of joined table (unless already
+    #     qualified), and value (2nd arg) is column of the last joined or primary table (or the
+    #     :implicit_qualifier option).
+    #     To specify multiple conditions on a single joined table column, you must use an array.
+    #     Uses a JOIN with an ON clause.
+    #   * Array - If all members of the array are symbols, considers them as columns and 
+    #     uses a JOIN with a USING clause.  Most databases will remove duplicate columns from
+    #     the result set if this is used.
+    #   * nil - If a block is not given, doesn't use ON or USING, so the JOIN should be a NATURAL
+    #     or CROSS join. If a block is given, uses a ON clause based on the block, see below.
+    #   * Everything else - pretty much the same as a using the argument in a call to filter,
+    #     so strings are considered literal, symbols specify boolean columns, and blockless
+    #     filter expressions can be used. Uses a JOIN with an ON clause.
+    # * options - a hash of options, with any of the following keys:
+    #   * :table_alias - the name of the table's alias when joining, necessary for joining
+    #     to the same table more than once.  No alias is used by default.
+    #   * :implicit_qualifier - The name to use for qualifying implicit conditions.  By default,
+    #     the last joined or primary table is used.
+    # * block - The block argument should only be given if a JOIN with an ON clause is used,
+    #   in which case it yields the table alias/name for the table currently being joined,
+    #   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)
+      using_join = expr.is_a?(Array) && !expr.empty? && expr.all?{|x| x.is_a?(Symbol)}
+      if using_join && !supports_join_using?
+        h = {}
+        expr.each{|s| h[s] = s}
+        return join_table(type, table, h, options)
+      end
+
+      case options
+      when Hash
+        table_alias = options[:table_alias]
+        last_alias = options[:implicit_qualifier]
+      when Symbol, String, SQL::Identifier
+        table_alias = options
+        last_alias = nil 
+      else
+        raise Error, "invalid options format for join_table: #{options.inspect}"
+      end
+
+      if Dataset === table
+        if table_alias.nil?
+          table_alias_num = (@opts[:num_dataset_sources] || 0) + 1
+          table_alias = dataset_alias(table_alias_num)
+        end
+        table_name = table_alias
+      else
+        table = table.table_name if table.respond_to?(:table_name)
+        table_name = table_alias || table
+      end
+
+      join = if expr.nil? and !block_given?
+        SQL::JoinClause.new(type, table, table_alias)
+      elsif using_join
+        raise(Sequel::Error, "can't use a block if providing an array of symbols as expr") if block_given?
+        SQL::JoinUsingClause.new(expr, type, table, table_alias)
+      else
+        last_alias ||= @opts[:last_joined_table] || first_source_alias
+        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)
+            [k,v]
+          end
+        end
+        if block_given?
+          expr2 = yield(table_name, last_alias, @opts[:join] || [])
+          expr = expr ? SQL::BooleanExpression.new(:AND, expr, expr2) : expr2
+        end
+        SQL::JoinOnClause.new(expr, type, table, table_alias)
+      end
+
+      opts = {:join => (@opts[:join] || []) + [join], :last_joined_table => table_name}
+      opts[:num_dataset_sources] = table_alias_num if table_alias_num
+      clone(opts)
+    end
+    
+    CONDITIONED_JOIN_TYPES.each do |jtype|
+      class_eval("def #{jtype}_join(*args, &block); join_table(:#{jtype}, *args, &block) end", __FILE__, __LINE__)
+    end
+    UNCONDITIONED_JOIN_TYPES.each do |jtype|
+      class_eval("def #{jtype}_join(table); raise(Sequel::Error, '#{jtype}_join does not accept join table blocks') if block_given?; join_table(:#{jtype}, table) end", __FILE__, __LINE__)
+    end
+    alias join inner_join
+
+    # 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.last - l.first + (l.exclude_end? ? 0 : 1)
+      end
+      l = l.to_i if l.is_a?(String) && !l.is_a?(LiteralString)
+      if l.is_a?(Integer)
+        raise(Error, 'Limits must be greater than or equal to 1') unless l >= 1
+      end
+      opts = {:limit => l}
+      if o
+        o = o.to_i if o.is_a?(String) && !o.is_a?(LiteralString)
+        if o.is_a?(Integer)
+          raise(Error, 'Offsets must be greater than or equal to 0') unless o >= 0
+        end
+        opts[:offset] = o
+      end
+      clone(opts)
+    end
+    
+    # Returns a cloned dataset with the given lock style.  If style is a
+    # string, it will be used directly.  Otherwise, a symbol may be used
+    # for database independent locking.  Currently :update is respected
+    # by most databases, and :share is supported by some.
+    def lock_style(style)
+      clone(:lock => style)
+    end
+    
+    # Returns a naked dataset clone - i.e. a dataset that returns records as
+    # hashes instead of calling the row proc.
+    def naked
+      ds = clone
+      ds.row_proc = nil
+      ds
+    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
+      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.  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'
+    #   ds.order('a + b'.lit).sql #=> 'SELECT * FROM items ORDER BY a + b'
+    #   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{|o| o.sum(:name)}.sql #=> 'SELECT * FROM items ORDER BY sum(name)'
+    #   ds.order(nil).sql #=> 'SELECT * FROM items'
+    def order(*columns, &block)
+      columns += Array(Sequel.virtual_row(&block)) if block
+      clone(:order => (columns.compact.empty?) ? nil : columns)
+    end
+    alias order_by order
+    
+    # Returns a copy of the dataset with the order columns added
+    # to the existing order.
+    #
+    #   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)
+      columns = @opts[:order] + columns if @opts[:order]
+      order(*columns, &block)
+    end
+    
+    # Qualify to the given table, or first source if not table is given.
+    def qualify(table=first_source)
+      qualify_to(table)
+    end
+
+    # Return a copy of the dataset with unqualified identifiers in the
+    # SELECT, WHERE, GROUP, HAVING, and ORDER clauses qualified by the
+    # given table. If no columns are currently selected, select all
+    # columns of the given table.
+    def qualify_to(table)
+      o = @opts
+      return clone if o[:sql]
+      h = {}
+      (o.keys & QUALIFY_KEYS).each do |k|
+        h[k] = qualified_expression(o[k], table)
+      end
+      h[:select] = [SQL::ColumnAll.new(table)] if !o[:select] || o[:select].empty?
+      clone(h)
+    end
+    
+    # Qualify the dataset to its current first source.  This is useful
+    # if you have unqualified identifiers in the query that all refer to
+    # the first source, and you want to join to another table which
+    # has columns with the same name as columns in the current dataset.
+    # See qualify_to.
+    def qualify_to_first_source
+      qualify_to(first_source)
+    end
+    
+    # Returns a copy of the dataset with the order reversed. If no order is
+    # given, the existing order is inverted.
+    def reverse_order(*order)
+      order(*invert_order(order.empty? ? @opts[:order] : order))
+    end
+    alias reverse reverse_order
+
+    # Returns a copy of the dataset with the columns selected changed
+    # 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(Sequel.virtual_row(&block)) if block
+      m = []
+      columns.map do |i|
+        i.is_a?(Hash) ? m.concat(i.map{|k, v| SQL::AliasedExpression.new(k,v)}) : m << i
+      end
+      clone(:select => m)
+    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.  If no columns are currently selected
+    # it will select the columns given in addition to *.
+    #
+    #   dataset.select(:a).select(:b) # SELECT b FROM items
+    #   dataset.select(:a).select_append(:b) # SELECT a, b FROM items
+    #   dataset.select_append(:b) # SELECT *, b FROM items
+    def select_append(*columns, &block)
+      cur_sel = @opts[:select]
+      cur_sel = [WILDCARD] if !cur_sel || cur_sel.empty?
+      select(*(cur_sel + columns), &block)
+    end
+
+    # Returns a copy of the dataset with the given columns added
+    # to the existing selected columns. If no columns are currently selected
+    # it will just select the columns given. 
+    #
+    #   dataset.select(:a).select(:b) # SELECT b FROM items
+    #   dataset.select(:a).select_more(:b) # SELECT a, b FROM items
+    #   dataset.select_more(:b) # SELECT b FROM items
+    def select_more(*columns, &block)
+      columns = @opts[:select] + columns if @opts[:select]
+      select(*columns, &block)
+    end
+    
+    # Set the server for this dataset to use.  Used to pick a specific database
+    # shard to run a query against, or to override the default (which is SELECT uses
+    # :read_only database and all other queries use the :default database).
+    def server(servr)
+      clone(:server=>servr)
+    end
+
+    # Set the default values for insert and update statements.  The values hash passed
+    # to insert or update are merged into this hash.
+    def set_defaults(hash)
+      clone(:defaults=>(@opts[:defaults]||{}).merge(hash))
+    end
+
+    # Set values that override hash arguments given to insert and update statements.
+    # This hash is merged into the hash provided to insert or update.
+    def set_overrides(hash)
+      clone(:overrides=>hash.merge(@opts[:overrides]||{}))
+    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 GROUP BY a
+    def unfiltered
+      clone(:where => nil, :having => nil)
+    end
+
+    # Returns a copy of the dataset with no grouping (GROUP or HAVING clause) applied.
+    # 
+    #   dataset.group(:a).having(:a=>1).where(:b).ungrouped # SELECT * FROM items WHERE b
+    def ungrouped
+      clone(:group => nil, :having => nil)
+    end
+
+    # Adds a UNION clause using a second dataset object.
+    # A UNION compound dataset returns all rows in either the current dataset
+    # or the given dataset.
+    # Options:
+    # * :all - Set to true to use UNION ALL instead of UNION, so duplicate rows can occur
+    # * :from_self - Set to false to not wrap the returned dataset in a from_self, use with care.
+    #
+    #   DB[:items].union(DB[:other_items]).sql
+    #   #=> "SELECT * FROM items UNION SELECT * FROM other_items"
+    def union(dataset, opts={})
+      opts = {:all=>opts} unless opts.is_a?(Hash)
+      compound_clone(:union, dataset, opts)
+    end
+    
+    # Returns a copy of the dataset with no limit or offset.
+    # 
+    #   dataset.limit(10, 20).unlimited # SELECT * FROM items
+    def unlimited
+      clone(:limit=>nil, :offset=>nil)
+    end
+
+    # Returns a copy of the dataset with no order.
+    # 
+    #   dataset.order(:a).unordered # SELECT * FROM items
+    def unordered
+      order(nil)
+    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
+    
+    # Add a simple common table expression (CTE) with the given name and a dataset that defines the CTE.
+    # A common table expression acts as an inline view for the query.
+    # Options:
+    # * :args - Specify the arguments/columns for the CTE, should be an array of symbols.
+    # * :recursive - Specify that this is a recursive CTE
+    def with(name, dataset, opts={})
+      raise(Error, 'This datatset does not support common table expressions') unless supports_cte?
+      clone(:with=>(@opts[:with]||[]) + [opts.merge(:name=>name, :dataset=>dataset)])
+    end
+
+    # Add a recursive common table expression (CTE) with the given name, a dataset that
+    # defines the nonrecursive part of the CTE, and a dataset that defines the recursive part
+    # of the CTE.  Options:
+    # * :args - Specify the arguments/columns for the CTE, should be an array of symbols.
+    # * :union_all - Set to false to use UNION instead of UNION ALL combining the nonrecursive and recursive parts.
+    def with_recursive(name, nonrecursive, recursive, opts={})
+      raise(Error, 'This datatset does not support common table expressions') unless supports_cte?
+      clone(:with=>(@opts[:with]||[]) + [opts.merge(:recursive=>true, :name=>name, :dataset=>nonrecursive.union(recursive, {:all=>opts[:union_all] != false, :from_self=>false}))])
+    end
+    
+    # Returns a copy of the dataset with the static SQL used.  This is useful if you want
+    # to keep the same row_proc/graph, but change the SQL used to custom 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
+    
+    protected
+
+    # Return true if the dataset has a non-nil value for any key in opts.
+    def options_overlap(opts)
+      !(@opts.collect{|k,v| k unless v.nil?}.compact & opts).empty?
+    end
+
+    # Whether this dataset is a simple SELECT * FROM table.
+    def simple_select_all?
+      o = @opts.reject{|k,v| v.nil? || NON_SQL_OPTIONS.include?(k)}
+      o.length == 1 && (f = o[:from]) && f.length == 1 && f.first.is_a?(Symbol)
+    end
+
+    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
+      if cond.respond_to?(:empty?) && cond.empty? && !block
+        clone
+      else
+        cond = filter_expr(cond, &block)
+        cond = SQL::BooleanExpression.new(:AND, @opts[clause], cond) if @opts[clause]
+        clone(clause => cond)
+      end
+    end
+    
+    # Add the dataset to the list of compounds
+    def compound_clone(type, dataset, opts)
+      ds = compound_from_self.clone(:compounds=>Array(@opts[:compounds]).map{|x| x.dup} + [[type, dataset.compound_from_self, opts[:all]]])
+      opts[:from_self] == false ? ds : ds.from_self(opts)
+    end
+
+    # SQL fragment based on the expr type.  See #filter.
+    def filter_expr(expr = nil, &block)
+      expr = nil if expr == []
+      if expr && block
+        return SQL::BooleanExpression.new(:AND, filter_expr(expr), filter_expr(block))
+      elsif block
+        expr = block
+      end
+      case expr
+      when Hash
+        SQL::BooleanExpression.from_value_pairs(expr)
+      when Array
+        if (sexpr = expr.at(0)).is_a?(String)
+          SQL::PlaceholderLiteralString.new(sexpr, expr[1..-1], true)
+        elsif Sequel.condition_specifier?(expr)
+          SQL::BooleanExpression.from_value_pairs(expr)
+        else
+          SQL::BooleanExpression.new(:AND, *expr.map{|x| filter_expr(x)})
+        end
+      when Proc
+        filter_expr(Sequel.virtual_row(&expr))
+      when SQL::NumericExpression, SQL::StringExpression
+        raise(Error, "Invalid SQL Expression type: #{expr.inspect}") 
+      when Symbol, SQL::Expression
+        expr
+      when TrueClass, FalseClass
+        SQL::BooleanExpression.new(:NOOP, expr)
+      when String
+        LiteralString.new("(#{expr})")
+      else
+        raise(Error, 'Invalid filter argument')
+      end
+    end
+    
+    # Inverts the given order by breaking it into a list of column references
+    # and inverting them.
+    #
+    #   dataset.invert_order([:id.desc]]) #=> [:id]
+    #   dataset.invert_order(:category, :price.desc]) #=>
+    #     [:category.desc, :price]
+    def invert_order(order)
+      return nil unless order
+      new_order = []
+      order.map do |f|
+        case f
+        when SQL::OrderedExpression
+          f.invert
+        else
+          SQL::OrderedExpression.new(f)
+        end
+      end
+    end
+  end
+end