sequel_core 1.0

data/lib/sequel_core/dataset.rb

@@ -0,0 +1,409 @@
+require 'time'
+require 'date'
+require 'yaml'
+
+require File.join(File.dirname(__FILE__), 'dataset/sql')
+require File.join(File.dirname(__FILE__), 'dataset/sequelizer')
+require File.join(File.dirname(__FILE__), 'dataset/convenience')
+
+module Sequel
+  # A Dataset represents a view of a the data in a database, constrained by
+  # specific parameters such as filtering conditions, order, etc. Datasets
+  # can be used to create, retrieve, update and delete records.
+  # 
+  # Query results are always retrieved on demand, so a dataset can be kept
+  # around and reused indefinitely:
+  #   my_posts = DB[:posts].filter(:author => 'david') # no records are retrieved
+  #   p my_posts.all # records are now retrieved
+  #   ...
+  #   p my_posts.all # records are retrieved again
+  #
+  # In order to provide this functionality, dataset methods such as where, 
+  # select, order, etc. return modified copies of the dataset, so you can
+  # use different datasets to access data:
+  #   posts = DB[:posts]
+  #   davids_posts = posts.filter(:author => 'david')
+  #   old_posts = posts.filter('stamp < ?', 1.week.ago)
+  #
+  # Datasets are Enumerable objects, so they can be manipulated using any
+  # of the Enumerable methods, such as map, inject, etc.
+  #
+  # === The Dataset Adapter Interface
+  #
+  # Each adapter should define its own dataset class as a descendant of
+  # Sequel::Dataset. The following methods should be overriden by the adapter
+  # Dataset class (each method with the stock implementation):
+  #
+  #   # Iterate over the results of the SQL query and call the supplied
+  #   # block with each record (as a hash).
+  #   def fetch_rows(sql, &block)
+  #     @db.synchronize do
+  #       r = @db.execute(sql)
+  #       r.each(&block)
+  #     end
+  #   end
+  #
+  #   # Insert records.
+  #   def insert(*values)
+  #     @db.synchronize do
+  #       @db.execute(insert_sql(*values)).last_insert_id
+  #     end
+  #   end
+  #
+  #   # Update records.
+  #   def update(*args, &block)
+  #     @db.synchronize do
+  #       @db.execute(update_sql(*args, &block)).affected_rows
+  #     end
+  #   end
+  #
+  #   # Delete records.
+  #   def delete(opts = nil)
+  #     @db.synchronize do
+  #       @db.execute(delete_sql(opts)).affected_rows
+  #     end
+  #   end
+  class Dataset
+    include Enumerable
+    include Sequelizer
+    include SQL
+    include Convenience
+    
+    attr_reader :db
+    attr_accessor :opts
+    
+    alias all to_a
+    alias size count
+  
+    # Constructs a new instance of a dataset with a database instance, initial
+    # options and an optional record class. Datasets are usually constructed by
+    # invoking Database methods:
+    #   DB[:posts]
+    # Or:
+    #   DB.dataset # the returned dataset is blank
+    #
+    # Sequel::Dataset is an abstract class that is not useful by itself. Each
+    # database adaptor should provide a descendant class of Sequel::Dataset.
+    def initialize(db, opts = nil)
+      @db = db
+      @opts = opts || {}
+      @row_proc = nil
+      @transform = nil
+    end
+    
+    # Returns a new instance of the dataset with with the give options merged.
+    def clone_merge(opts)
+      new_dataset = clone
+      new_dataset.set_options(@opts.merge(opts))
+      new_dataset
+    end
+    
+    def set_options(opts) #:nodoc:
+      @opts = opts
+      @columns = nil
+    end
+    
+    NOTIMPL_MSG = "This method must be overriden in Sequel adapters".freeze
+    
+    # Executes a select query and fetches records, passing each record to the
+    # supplied block. Adapters should override this method.
+    def fetch_rows(sql, &block)
+      # @db.synchronize do
+      #   r = @db.execute(sql)
+      #   r.each(&block)
+      # end
+      raise NotImplementedError, NOTIMPL_MSG
+    end
+  
+    # Inserts values into the associated table. Adapters should override this
+    # method.
+    def insert(*values)
+      # @db.synchronize do
+      #   @db.execute(insert_sql(*values)).last_insert_id
+      # end
+      raise NotImplementedError, NOTIMPL_MSG
+    end
+  
+    # Updates values for the dataset. Adapters should override this method.
+    def update(values, opts = nil)
+      # @db.synchronize do
+      #   @db.execute(update_sql(values, opts)).affected_rows
+      # end
+      raise NotImplementedError, NOTIMPL_MSG
+    end
+  
+    # Deletes the records in the dataset. Adapters should override this method.
+    def delete(opts = nil)
+      # @db.synchronize do
+      #   @db.execute(delete_sql(opts)).affected_rows
+      # end
+      raise NotImplementedError, NOTIMPL_MSG
+    end
+    
+    # Returns the columns in the result set in their true order. The stock 
+    # implementation returns the content of @columns. If @columns is nil,
+    # a query is performed. Adapters are expected to fill @columns with the
+    # column information when a query is performed.
+    def columns
+      first unless @columns
+      @columns || []
+    end
+    
+    # Inserts the supplied values into the associated table.
+    def <<(*args)
+      insert(*args)
+    end
+  
+    # Updates the dataset with the given values.
+    def set(*args, &block)
+      update(*args, &block)
+    end
+    
+    # Iterates over the records in the dataset
+    def each(opts = nil, &block)
+      fetch_rows(select_sql(opts), &block)
+      self
+    end
+
+    # Returns the the model classes associated with the dataset as a hash.
+    def model_classes
+      @opts[:models]
+    end
+    
+    # Returns the column name for the polymorphic key.
+    def polymorphic_key
+      @opts[:polymorphic_key]
+    end
+    
+    # Returns a naked dataset clone - i.e. a dataset that returns records as
+    # hashes rather than model objects.
+    def naked
+      d = clone_merge(:naked => true, :models => nil, :polymorphic_key => nil)
+      d.set_model(nil)
+      d
+    end
+    
+    # Associates or disassociates the dataset with a model. If no argument or
+    # nil is specified, the dataset is turned into a naked dataset and returns
+    # records as hashes. If a model class specified, the dataset is modified
+    # to return records as instances of the model class, e.g:
+    #
+    #   class MyModel
+    #     def initialize(values)
+    #       @values = values
+    #       ...
+    #     end
+    #   end
+    # 
+    #   dataset.set_model(MyModel)
+    #
+    # You can also provide additional arguments to be passed to the model's
+    # initialize method:
+    #
+    #   class MyModel
+    #     def initialize(values, options)
+    #       @values = values
+    #       ...
+    #     end
+    #   end
+    # 
+    #   dataset.set_model(MyModel, :allow_delete => false)
+    #  
+    # The dataset can be made polymorphic by specifying a column name as the
+    # polymorphic key and a hash mapping column values to model classes.
+    #
+    #   dataset.set_model(:kind, {1 => Person, 2 => Business})
+    #
+    # You can also set a default model class to fall back on by specifying a
+    # class corresponding to nil:
+    #
+    #   dataset.set_model(:kind, {nil => DefaultClass, 1 => Person, 2 => Business})
+    # 
+    # To disassociate a model from the dataset, you can call the #set_model 
+    # and specify nil as the class:
+    # 
+    #   dataset.set_model(nil)
+    #
+    def set_model(key, *args)
+      # pattern matching
+      case key
+      when nil # set_model(nil) => no
+        # no argument provided, so the dataset is denuded
+        @opts.merge!(:naked => true, :models => nil, :polymorphic_key => nil)
+        remove_row_proc
+        # extend_with_stock_each
+      when Class
+        # isomorphic model
+        @opts.merge!(:naked => nil, :models => {nil => key}, :polymorphic_key => nil)
+        set_row_proc {|h| key.new(h, *args)}
+        extend_with_destroy
+      when Symbol
+        # polymorphic model
+        hash = args.shift || raise(ArgumentError, "No class hash supplied for polymorphic model")
+        @opts.merge!(:naked => true, :models => hash, :polymorphic_key => key)
+        set_row_proc do |h|
+          c = hash[h[key]] || hash[nil] || \
+            raise(Error, "No matching model class for record (#{polymorphic_key} => #{h[polymorphic_key].inspect})")
+          c.new(h, *args)
+        end
+        extend_with_destroy
+      else
+        raise ArgumentError, "Invalid model specified"
+      end
+      self
+    end
+    
+    # Overrides the each method to pass the values through a filter. The filter
+    # receives as argument a hash containing the column values for the current
+    # record. The filter should return a value which is then passed to the 
+    # iterating block. In order to elucidate, here's a contrived example:
+    #
+    #   dataset.set_row_proc {|h| h.merge(:xxx => 'yyy')}
+    #   dataset.first[:xxx] #=> "yyy" # always!
+    #
+    def set_row_proc(&filter)
+      @row_proc = filter
+      update_each_method
+    end
+    
+    # Removes the row making proc.
+    def remove_row_proc
+      @row_proc = nil
+      update_each_method
+    end
+    
+    STOCK_TRANSFORMS = {
+      :marshal => [proc {|v| Marshal.load(v)}, proc {|v| Marshal.dump(v)}],
+      :yaml => [proc {|v| YAML.load v if v}, proc {|v| v.to_yaml}]
+    }
+    
+    # Sets a value transform which is used to convert values loaded and saved
+    # to/from the database. The transform should be supplied as a hash. Each
+    # value in the hash should be an array containing two proc objects - one
+    # for transforming loaded values, and one for transforming saved values.
+    # The following example demonstrates how to store Ruby objects in a dataset
+    # using Marshal serialization:
+    #
+    #   dataset.transform(:obj => [
+    #     proc {|v| Marshal.load(v)},
+    #     proc {|v| Marshal.dump(v)}
+    #   ])
+    #
+    #   dataset.insert_sql(:obj => 1234) #=>
+    #   "INSERT INTO items (obj) VALUES ('\004\bi\002\322\004')"
+    #
+    # Another form of using transform is by specifying stock transforms:
+    # 
+    #   dataset.transform(:obj => :marshal)
+    #
+    # The currently supported stock transforms are :marshal and :yaml.
+    def transform(t)
+      @transform = t
+      t.each do |k, v|
+        case v
+        when Array
+          if (v.size != 2) || !v.first.is_a?(Proc) && !v.last.is_a?(Proc)
+            raise Error::InvalidTransform, "Invalid transform specified"
+          end
+        else
+          unless v = STOCK_TRANSFORMS[v]
+            raise Error::InvalidTransform, "Invalid transform specified"
+          else
+            t[k] = v
+          end
+        end
+      end
+      update_each_method
+      self
+    end
+    
+    # Applies the value transform for data loaded from the database.
+    def transform_load(r)
+      @transform.each do |k, tt|
+        if r.has_key?(k)
+          r[k] = tt[0][r[k]]
+        end
+      end
+      r
+    end
+    
+    # Applies the value transform for data saved to the database.
+    def transform_save(r)
+      @transform.each do |k, tt|
+        if r.has_key?(k)
+          r[k] = tt[1][r[k]]
+        end
+      end
+      r
+    end
+    
+    # Updates the each method according to whether @row_proc and @transform are
+    # set or not.
+    def update_each_method
+      # warning: ugly code generation ahead
+      if @row_proc && @transform
+        class << self
+          def each(opts = nil, &block)
+            if opts && opts[:naked]
+              fetch_rows(select_sql(opts)) {|r| block[transform_load(r)]}
+            else
+              fetch_rows(select_sql(opts)) {|r| block[@row_proc[transform_load(r)]]}
+            end
+            self
+          end
+        end
+      elsif @row_proc
+        class << self
+          def each(opts = nil, &block)
+            if opts && opts[:naked]
+              fetch_rows(select_sql(opts), &block)
+            else
+              fetch_rows(select_sql(opts)) {|r| block[@row_proc[r]]}
+            end
+            self
+          end
+        end
+      elsif @transform
+        class << self
+          def each(opts = nil, &block)
+            fetch_rows(select_sql(opts)) {|r| block[transform_load(r)]}
+            self
+          end
+        end
+      else
+        class << self
+          def each(opts = nil, &block)
+            fetch_rows(select_sql(opts), &block)
+            self
+          end
+        end
+      end
+    end
+    
+    # Extends the dataset with a destroy method, that calls destroy for each
+    # record in the dataset.
+    def extend_with_destroy
+      unless respond_to?(:destroy)
+        meta_def(:destroy) do
+          unless @opts[:models]
+            raise Error, "No model associated with this dataset"
+          end
+          count = 0
+          @db.transaction {each {|r| count += 1; r.destroy}}
+          count
+        end
+      end
+    end
+
+    @@dataset_classes = []
+
+    def self.dataset_classes #:nodoc:
+      @@dataset_classes
+    end
+
+    def self.inherited(c) #:nodoc:
+      @@dataset_classes << c
+    end
+  end
+end
+

data/lib/sequel_core/dataset/convenience.rb

@@ -0,0 +1,321 @@
+require 'enumerator'
+
+module Sequel
+  class Dataset
+    module Convenience
+      # Iterates through each record, converting it into a hash.
+      def each_hash(&block)
+        each {|a| block[a.to_hash]}
+      end
+      
+      # Returns true if the record count is 0
+      def empty?
+        count == 0
+      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 nill if dataset is empty.
+      def single_value(opts = nil)
+        opts = opts ? NAKED_HASH.merge(opts) : NAKED_HASH
+        # reset the columns cache so it won't fuck subsequent calls to columns
+        each(opts) {|r| @columns = nil; return r.values.first}
+        nil
+      end
+
+      # 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 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])
+
+        args = args.empty? ? 1 : (args.size == 1) ? args.first : args
+
+        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_merge(opts).all
+          end
+        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)
+        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
+
+      # 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)
+        record_count = count
+        total_pages = (record_count / page_size.to_f).ceil
+        paginated = limit(page_size, (page_no - 1) * page_size)
+        paginated.set_pagination_info(page_no, page_size, record_count)
+        paginated
+      end
+      
+      # 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
+
+      attr_accessor :page_size, :page_count, :current_page, :pagination_record_count
+
+      # 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
+
+      # 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
+        
+        a = 1 + (@current_page - 1) * @page_size
+        b = a + @page_size - 1
+        b = @pagination_record_count if b > @pagination_record_count
+        a..b
+      end
+
+      # Returns the number of records in the current page
+      def current_page_record_count
+        return 0 if @current_page > @page_count
+        
+        a = 1 + (@current_page - 1) * @page_size
+        b = a + @page_size - 1
+        b = @pagination_record_count if b > @pagination_record_count
+        b - a + 1
+      end
+
+      # Returns the minimum value for the given column.
+      def min(column)
+        single_value(:select => [column.MIN.AS(:v)])
+      end
+
+      # Returns the maximum value for the given column.
+      def max(column)
+        single_value(:select => [column.MAX.AS(:v)])
+      end
+
+      # Returns the sum for the given column.
+      def sum(column)
+        single_value(:select => [column.SUM.AS(:v)])
+      end
+
+      # Returns the average value for the given column.
+      def avg(column)
+        single_value(:select => [column.AVG.AS(:v)])
+      end
+      
+      # Returns a dataset grouped by the given column with count by group.
+      def group_and_count(column)
+        group(column).select(column, :count[column].AS(:count)).order(:count)
+      end
+      
+      # Returns a Range object made from the minimum and maximum values for the
+      # given column.
+      def range(column)
+        r = select(column.MIN.AS(:v1), column.MAX.AS(:v2)).first
+        r && (r[:v1]..r[:v2])
+      end
+      
+      # Returns the interval between minimum and maximum values for the given 
+      # column.
+      def interval(column)
+        r = select("(max(#{literal(column)}) - min(#{literal(column)})) AS v".lit).first
+        r && r[:v]
+      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)
+        records = naked.to_a
+        csv = ''
+        if include_column_titles
+          csv << "#{@columns.join(COMMA_SEPARATOR)}\r\n"
+        end
+        records.each {|r| csv << "#{r.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. If the :commit_every 
+      # option is specified, the method will generate a separate transaction 
+      # for each batch of records, e.g.:
+      #
+      #   dataset.multi_insert(list, :commit_every => 1000)
+      def multi_insert(list, opts = {})
+        if every = opts[:commit_every]
+          list.each_slice(every) do |s|
+            @db.transaction do
+              s.each {|r| @db.execute(insert_sql(r))}
+              # @db.execute(s.map {|r| insert_sql(r)}.join)
+            end
+          end
+        else
+          @db.transaction do
+            # @db.execute(list.map {|r| insert_sql(r)}.join)
+            list.each {|r| @db.execute(insert_sql(r))}
+          end
+        end
+      end
+      
+      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
+        
+        def clone_merge(opts)
+          @opts.merge!(opts)
+        end
+      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_merge({})
+        copy.extend(QueryBlockCopy)
+        copy.instance_eval(&block)
+        clone_merge(copy.opts)
+      end
+      
+      MUTATION_RE = /^(.+)!$/.freeze
+
+      # Provides support for mutation methods (filter!, order!, etc.) and magic
+      # methods.
+      def method_missing(m, *args, &block)
+        if m.to_s =~ MUTATION_RE
+          m = $1.to_sym
+          super unless respond_to?(m)
+          copy = send(m, *args, &block)
+          super if copy.class != self.class
+          @opts.merge!(copy.opts)
+          self
+        elsif magic_method_missing(m)
+          send(m, *args)
+        else
+           super
+        end
+      end
+      
+      MAGIC_METHODS = {
+        /^order_by_(.+)$/   => proc {|c| proc {order(c)}},
+        /^first_by_(.+)$/   => proc {|c| proc {order(c).first}},
+        /^last_by_(.+)$/    => proc {|c| proc {order(c).last}},
+        /^filter_by_(.+)$/  => proc {|c| proc {|v| filter(c => v)}},
+        /^all_by_(.+)$/     => proc {|c| proc {|v| filter(c => v).all}},
+        /^find_by_(.+)$/    => proc {|c| proc {|v| filter(c => v).first}},
+        /^group_by_(.+)$/   => proc {|c| proc {group(c)}},
+        /^count_by_(.+)$/   => proc {|c| proc {group_and_count(c)}}
+      }
+
+      # Checks if the given method name represents a magic method and 
+      # defines it. Otherwise, nil is returned.
+      def magic_method_missing(m)
+        method_name = m.to_s
+        MAGIC_METHODS.each_pair do |r, p|
+          if method_name =~ r
+            impl = p[$1.to_sym]
+            return Dataset.class_def(m, &impl)
+          end
+        end
+        nil
+      end
+      
+      def create_view(name)
+        @db.create_view(name, self)
+      end
+      
+      def create_or_replace_view(name)
+        @db.create_or_replace_view(name, self)
+      end
+    end
+  end
+end