sequel_core 1.5.1 → 2.0.0

data/lib/sequel_core/dataset/callback.rb

@@ -1,17 +1,16 @@
+# This file holds empty methods that can be
+# overridden to provide callback behavior.
+
 module Sequel
   class Dataset
-    # Module with empty methods that can be
-    # override to provide callback behavior
-    module Callback
-      private
-        # This is run inside .all, after all
-        # of the records have been loaded
-        # via .each, but before any block passed
-        # to all is called.  It is called with
-        # a single argument, an array of all
-        # returned records.
-        def post_load(all_records)
-        end
+    private
+    # This is run inside .all, after all
+    # of the records have been loaded
+    # via .each, but before any block passed
+    # to all is called.  It is called with
+    # a single argument, an array of all
+    # returned records.
+    def post_load(all_records)
     end
   end
 end

data/lib/sequel_core/dataset/convenience.rb

@@ -1,270 +1,243 @@
-require 'enumerator'
-
 module Sequel
   class Dataset
-    module Convenience
-      # Returns true if no records exists in the dataset
-      def empty?
-        db.dataset.where(exists).get(1) == nil
-      end
-      
-      # Returns the first record in the dataset.
-      def single_record(opts = nil)
-        each(opts) {|r| return r}
-        nil
-      end
-      
-      NAKED_HASH = {:naked => true}.freeze
-
-      # Returns the first value of the first reecord in the dataset.
-      # Returns nil if dataset is empty.
-      def single_value(opts = nil)
-        opts = opts ? NAKED_HASH.merge(opts) : NAKED_HASH
-        # don't cache the columns
-        each(opts) {|r| @columns = nil; return r.values.first}
-        nil
-      end
-      
-      def get(column)
-        select(column).single_value
-      end
+    COMMA_SEPARATOR = ', '.freeze
+    COUNT_OF_ALL_AS_COUNT = :count['*'.lit].as(:count)
 
-      # Returns the first record in the dataset. If the num argument is specified,
-      # an array is returned with the first <i>num</i> records.
-      def first(*args, &block)
-        if block
-          return filter(&block).single_record(:limit => 1)
-        end
-        args = args.empty? ? 1 : (args.size == 1) ? args.first : args
-        case args
-        when 1
-          single_record(:limit => 1)
-        when Fixnum
-          limit(args).all
-        else
-          filter(args, &block).single_record(:limit => 1)
-        end
-      end
-
-      # Returns the first record matching the condition.
-      def [](*conditions)
-        first(*conditions)
-      end
-
-      def []=(conditions, values)
-        filter(conditions).update(values)
-      end
+    # Returns the first record matching the conditions.
+    def [](*conditions)
+      first(*conditions)
+    end
 
-      # Returns the last records in the dataset by inverting the order. If no
-      # order is given, an exception is raised. If num is not given, the last
-      # record is returned. Otherwise an array is returned with the last 
-      # <i>num</i> records.
-      def last(*args)
-        raise Error, 'No order specified' unless 
-          @opts[:order] || (opts && opts[:order])
+    # Update all records matching the conditions
+    # with the values specified.
+    def []=(conditions, values)
+      filter(conditions).update(values)
+    end
 
-        args = args.empty? ? 1 : (args.size == 1) ? args.first : args
+    # Returns the average value for the given column.
+    def avg(column)
+      get(:avg[column])
+    end
+    
+    # Returns true if no records exists in the dataset
+    def empty?
+      db.dataset.where(exists).get(1) == nil
+    end
+    
+    # Returns the first record in the dataset. If a numeric 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:
+    # 
+    #   ds.first => {:id=>7}
+    #   ds.first(2) => [{:id=>6}, {:id=>4}]
+    #   ds.order(:id).first(2) => [{:id=>1}, {:id=>2}]
+    #   ds.first(:id=>2) => {:id=>2}
+    #   ds.first("id = 3") => {:id=>3}
+    #   ds.first("id = ?", 4) => {:id=>4}
+    #   ds.first{:id > 2} => {:id=>5}
+    #   ds.order(:id).first{:id > 2} => {:id=>3}
+    #   ds.first{:id > 2} => {:id=>5}
+    #   ds.first("id > ?", 4){:id < 6) => {:id=>5}
+    #   ds.order(:id).first(2){:id < 2} => [{:id=>1}]
+    def first(*args, &block)
+      ds = block ? filter(&block) : self
 
-        case args
-        when Fixnum
-          l = {:limit => args}
-          opts = {:order => invert_order(@opts[:order])}. \
-            merge(opts ? opts.merge(l) : l)
-          if args == 1
-            single_record(opts)
-          else
-            clone(opts).all
-          end
+      if args.empty?
+        ds.single_record
+      else
+        args = (args.size == 1) ? args.first : args
+        if Integer === args
+          ds.limit(args).all
         else
-          filter(args).last(1)
-        end
-      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]}
-        else
-          super(&block)
+          ds.filter(args).single_record
         end
       end
+    end
 
-      # Returns a hash with one column used as key and another used as value.
-      def to_hash(key_column, value_column)
-        inject({}) do |m, r|
-          m[r[key_column]] = r[value_column]
-          m
-        end
-      end
+    # Return the column value for the first matching record in the dataset.
+    def get(column)
+      select(column).single_value
+    end
 
-      # Returns the minimum value for the given column.
-      def min(column)
-        single_value(:select => [:min[column].as(:v)])
-      end
+    # Returns a dataset grouped by the given column with count by group.
+    def group_and_count(*columns)
+      group(*columns).select(*(columns + [COUNT_OF_ALL_AS_COUNT])).order(:count)
+    end
+    
+    # Returns the interval between minimum and maximum values for the given 
+    # column.
+    def interval(column)
+      get("(max(#{literal(column)}) - min(#{literal(column)}))".lit)
+    end
 
-      # Returns the maximum value for the given column.
-      def max(column)
-        single_value(:select => [:max[column].as(:v)])
+    # Reverses the order and then runs first.  Note that this
+    # will not necessarily give you the last record in the dataset,
+    # unless you have an unambiguous order.  If there is not
+    # currently an order for this dataset, raises an Error.
+    def last(*args, &block)
+      raise(Error, 'No order specified') unless @opts[:order]
+      reverse.first(*args, &block)
+    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]}
+      else
+        super(&block)
       end
+    end
 
-      # Returns the sum for the given column.
-      def sum(column)
-        single_value(:select => [:sum[column].as(:v)])
-      end
+    # Returns the maximum value for the given column.
+    def max(column)
+      get(:max[column])
+    end
 
-      # Returns the average value for the given column.
-      def avg(column)
-        single_value(:select => [:avg[column].as(:v)])
-      end
-      
-      COUNT_OF_ALL_AS_COUNT = :count['*'.lit].as(:count)
-      
-      # Returns a dataset grouped by the given column with count by group.
-      def group_and_count(*columns)
-        group(*columns).select(columns + [COUNT_OF_ALL_AS_COUNT]).order(:count)
-      end
-      
-      # Returns a Range object made from the minimum and maximum values for the
-      # given column.
-      def range(column)
-        if r = select(:min[column].as(:v1), :max[column].as(:v2)).first
-          (r[:v1]..r[:v2])
-        end
-      end
-      
-      # Returns the interval between minimum and maximum values for the given 
-      # column.
-      def interval(column)
-        if r = select("(max(#{literal(column)}) - min(#{literal(column)})) AS v".lit).first
-          r[:v]
-        end
-      end
+    # Returns the minimum value for the given column.
+    def min(column)
+      get(:min[column])
+    end
 
-      # Pretty prints the records in the dataset as plain-text table.
-      def print(*cols)
-        Sequel::PrettyTable.print(naked.all, cols.empty? ? columns : cols)
-      end
-      
-      COMMA_SEPARATOR = ', '.freeze
-      
-      # Returns a string in CSV format containing the dataset records. By 
-      # default the CSV representation includes the column titles in the
-      # first line. You can turn that off by passing false as the 
-      # include_column_titles argument.
-      def to_csv(include_column_titles = true)
-        n = naked
-        cols = n.columns
-        csv = ''
-        csv << "#{cols.join(COMMA_SEPARATOR)}\r\n" if include_column_titles
-        n.each{|r| csv << "#{cols.collect{|c| r[c]}.join(COMMA_SEPARATOR)}\r\n"}
-        csv
-      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 can be called either with an array of hashes:
-      # 
-      #   dataset.multi_insert({:x => 1}, {:x => 2})
-      #
-      # Or with a columns array and an array of value arrays:
-      #
-      #   dataset.multi_insert([:x, :y], [[1, 2], [3, 4]])
-      #
-      # 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)
-      def multi_insert(*args)
-        if args.empty?
-          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 #{table} (#{literal(columns)}) VALUES (#{dataset.sql})"
-          return @db.transaction {@db.execute sql}
-        else
-          # we assume that an array of hashes is given
-          hashes, opts = *args
-          return if hashes.empty?
-          columns = hashes.first.keys
-          # 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| @db.execute(st)}}
-          end
-        else
-          statements = multi_insert_sql(columns, values)
+    # 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:
+    # 
+    #   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)
+    def multi_insert(*args)
+      if args.empty?
+        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)} #{literal(columns)} VALUES #{literal(dataset)}"
+        return @db.transaction {@db.execute sql}
+      else
+        # we assume that an array of hashes is given
+        hashes, opts = *args
+        return if hashes.empty?
+        columns = hashes.first.keys
+        # 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| @db.execute(st)}}
         end
+      else
+        statements = multi_insert_sql(columns, values)
+        @db.transaction {statements.each {|st| @db.execute(st)}}
       end
-      alias_method :import, :multi_insert
-      
-      module QueryBlockCopy #:nodoc:
-        def each(*args); raise Error, "#each cannot be invoked inside a query block."; end
-        def insert(*args); raise Error, "#insert cannot be invoked inside a query block."; end
-        def update(*args); raise Error, "#update cannot be invoked inside a query block."; end
-        def delete(*args); raise Error, "#delete cannot be invoked inside a query block."; 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)
+    end
+    
+    # Returns a Range object made from the minimum and maximum values for the
+    # given column.
+    def range(column)
+      if r = select(:min[column].as(:v1), :max[column].as(:v2)).first
+        (r[:v1]..r[:v2])
+      end
+    end
+    
+    # Returns the first record in the dataset.
+    def single_record(opts = nil)
+      each((opts||{}).merge(:limit=>1)){|r| return r}
+      nil
+    end
 
-        def clone(opts = nil)
-          @opts.merge!(opts)
-          self
-        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 = naked.single_record(opts)
+        r.values.first
       end
-      
-      # Translates a query block into a dataset. Query blocks can be useful
-      # when expressing complex SELECT statements, e.g.:
-      #
-      #   dataset = DB[:items].query do
-      #     select :x, :y, :z
-      #     where {:x > 1 && :y > 2}
-      #     order_by :z.DESC
-      #   end
-      #
-      def query(&block)
-        copy = clone({})
-        copy.extend(QueryBlockCopy)
-        copy.instance_eval(&block)
-        clone(copy.opts)
+    end
+    
+    # Returns the sum for the given column.
+    def sum(column)
+      get(:sum[column])
+    end
+
+    # Returns true if the table exists.  Will raise an error
+    # if the dataset has fixed SQL or selects from another dataset
+    # or more than one table.
+    def table_exists?
+      if @opts[:sql]
+        raise Sequel::Error, "this dataset has fixed SQL"
       end
       
-      def create_view(name)
-        @db.create_view(name, self)
+      if @opts[:from].size != 1
+        raise Sequel::Error, "this dataset selects from multiple sources"
       end
       
-      def create_or_replace_view(name)
-        @db.create_or_replace_view(name, self)
+      t = @opts[:from].first
+      if t.is_a?(Dataset)
+        raise Sequel::Error, "this dataset selects from a sub query"
       end
       
-      def table_exists?
-        if @opts[:sql]
-          raise Sequel::Error, "this dataset has fixed SQL"
-        end
-        
-        if @opts[:from].size != 1
-          raise Sequel::Error, "this dataset selects from multiple sources"
-        end
-        
-        t = @opts[:from].first
-        if t.is_a?(Dataset)
-          raise Sequel::Error, "this dataset selects from a sub query"
-        end
-        
-        @db.table_exists?(t.to_sym)
+      @db.table_exists?(t.to_sym)
+    end
+
+    # Returns a string in CSV format containing the dataset records. By 
+    # default the CSV representation includes the column titles in the
+    # first line. You can turn that off by passing false as the 
+    # include_column_titles argument.
+    #
+    # 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.
+    def to_csv(include_column_titles = true)
+      n = naked
+      cols = n.columns
+      csv = ''
+      csv << "#{cols.join(COMMA_SEPARATOR)}\r\n" if include_column_titles
+      n.each{|r| csv << "#{cols.collect{|c| r[c]}.join(COMMA_SEPARATOR)}\r\n"}
+      csv
+    end
+    
+    # Returns a hash with one column used as key and another used as value.
+    # If rows have duplicate values for the key column, the latter row(s)
+    # will overwrite the value of the previous row(s).
+    def to_hash(key_column, value_column)
+      inject({}) do |m, r|
+        m[r[key_column]] = r[value_column]
+        m
       end
     end
   end

data/lib/sequel_core/dataset/pagination.rb

@@ -1,62 +1,43 @@
-require 'enumerator'
-
 module Sequel
   class Dataset
-    # Returns a paginated dataset. The resulting dataset also provides the
-    # total number of pages (Dataset#page_count) and the current page number
-    # (Dataset#current_page), as well as Dataset#prev_page and Dataset#next_page
-    # for implementing pagination controls.
-    def paginate(page_no, page_size)
+    # Returns a paginated dataset. The returned dataset is limited to
+    # the page size at the correct offset, and extended with the Pagination
+    # module.  If a record count is not provided, does a count of total
+    # number of records for this dataset.
+    def paginate(page_no, page_size, record_count=nil)
       raise(Error, "You cannot paginate a dataset that already has a limit") if @opts[:limit]
-      record_count = count
-      total_pages = (record_count / page_size.to_f).ceil
       paginated = limit(page_size, (page_no - 1) * page_size)
       paginated.extend(Pagination)
-      paginated.set_pagination_info(page_no, page_size, record_count)
-      paginated
+      paginated.set_pagination_info(page_no, page_size, record_count || count)
     end
       
-    def each_page(page_size)
+    # Yields a paginated dataset for each page and returns the receiver. Does
+    # a count to find the total number of records for this dataset.
+    def each_page(page_size, &block)
       raise(Error, "You cannot paginate a dataset that already has a limit") if @opts[:limit]
       record_count = count
       total_pages = (record_count / page_size.to_f).ceil
-      
-      (1..total_pages).each do |page_no|
-        paginated = limit(page_size, (page_no - 1) * page_size)
-        paginated.extend(Pagination)
-        paginated.set_pagination_info(page_no, page_size, record_count)
-        yield paginated
-      end
-      
+      (1..total_pages).each{|page_no| yield paginate(page_no, page_size, record_count)}
       self
     end
 
+    # Holds methods that only relate to paginated datasets. Paginated dataset
+    # have pages starting at 1 (page 1 is offset 0, page 1 is offset page_size).
     module Pagination
-      attr_accessor :page_size, :page_count, :current_page, :pagination_record_count
+      # The number of records per page (the final page may have fewer than
+      # this number of records).
+      attr_accessor :page_size
 
-      # Sets the pagination info
-      def set_pagination_info(page_no, page_size, record_count)
-        @current_page = page_no
-        @page_size = page_size
-        @pagination_record_count = record_count
-        @page_count = (record_count / page_size.to_f).ceil
-      end
-      
-      # Returns the previous page number or nil if the current page is the first
-      def prev_page
-        current_page > 1 ? (current_page - 1) : nil
-      end
+      # The number of pages in the dataset before pagination, of which
+      # this paginated dataset is one.
+      attr_accessor :page_count
+
+      # The current page of the dataset, starting at 1 and not 0.
+      attr_accessor :current_page
+
+      # The total number of records in the dataset before pagination.
+      attr_accessor :pagination_record_count
 
-      # Returns the next page number or nil if the current page is the last page
-      def next_page
-        current_page < page_count ? (current_page + 1) : nil
-      end
-      
-      # Returns the page range
-      def page_range
-        1..page_count
-      end
-      
       # Returns the record range for the current page
       def current_page_record_range
         return (0..0) if @current_page > @page_count
@@ -76,6 +57,40 @@ module Sequel
         b = @pagination_record_count if b > @pagination_record_count
         b - a + 1
       end
+
+      # Returns true if the current page is the first page
+      def first_page?
+        @current_page == 1
+      end
+
+      # Returns true if the current page is the last page
+      def last_page?
+        @current_page == @page_count
+      end
+
+      # Returns the next page number or nil if the current page is the last page
+      def next_page
+        current_page < page_count ? (current_page + 1) : nil
+      end
+      
+      # Returns the page range
+      def page_range
+        1..page_count
+      end
+      
+      # Returns the previous page number or nil if the current page is the first
+      def prev_page
+        current_page > 1 ? (current_page - 1) : nil
+      end
+
+      # Sets the pagination info for this paginated dataset, and returns self.
+      def set_pagination_info(page_no, page_size, record_count)
+        @current_page = page_no
+        @page_size = page_size
+        @pagination_record_count = record_count
+        @page_count = (record_count / page_size.to_f).ceil
+        self
+      end
     end
   end
 end