sequel 0.5.0.2 → 1.0

data/lib/sequel/dataset.rb

@@ -1,409 +0,0 @@
-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/dataset/convenience.rb

@@ -1,321 +0,0 @@
-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