sequel 3.0.0 → 3.1.0

data/lib/sequel/model/base.rb

@@ -86,12 +86,7 @@ module Sequel
       # the given argument(s).  
       def [](*args)
         args = args.first if (args.size == 1)
-        return dataset[args] if args.is_a?(Hash)
-        if t = simple_table and p = simple_pk
-          with_sql("SELECT * FROM #{t} WHERE #{p} = #{dataset.literal(args)}").first
-        else
-          dataset[primary_key_hash(args)]
-        end
+        args.is_a?(Hash) ? dataset[args] : primary_key_lookup(args)
       end
       
       # Returns the columns in the result set in their original order.
@@ -380,8 +375,8 @@ module Sequel
         im = instance_methods.collect{|x| x.to_s}
         columns.each do |column|
           meth = "#{column}="
-          overridable_methods_module.module_eval("def #{column}; self[:#{column}] end") unless im.include?(column.to_s)
-          overridable_methods_module.module_eval("def #{meth}(v); self[:#{column}] = v end") unless im.include?(meth)
+          overridable_methods_module.module_eval("def #{column}; self[:#{column}] end", __FILE__, __LINE__) unless im.include?(column.to_s)
+          overridable_methods_module.module_eval("def #{meth}(v); self[:#{column}] = v end", __FILE__, __LINE__) unless im.include?(meth)
         end
       end
   
@@ -432,6 +427,16 @@ module Sequel
         include(@overridable_methods_module = Module.new) unless @overridable_methods_module
         @overridable_methods_module
       end
+      
+      # Find the row in the dataset that matches the primary key.  Uses
+      # an static SQL optimization if the table and primary key are simple.
+      def primary_key_lookup(pk)
+        if t = simple_table and p = simple_pk
+          with_sql("SELECT * FROM #{t} WHERE #{p} = #{dataset.literal(pk)}").first
+        else
+          dataset[primary_key_hash(pk)]
+        end
+      end
   
       # Set the columns for this model and create accessor methods for each column.
       def set_columns(new_columns)
@@ -634,12 +639,7 @@ module Sequel
       # If the model has a composite primary key, returns an array of values.
       def pk
         raise(Error, "No primary key is associated with this model") unless key = primary_key
-        case key
-        when Array
-          key.collect{|k| @values[k]}
-        else
-          @values[key]
-        end
+        key.is_a?(Array) ? key.map{|k| @values[k]} : @values[key]
       end
       
       # Returns a hash identifying the model instance.  It should be true that:

data/lib/sequel/model/plugins.rb

@@ -3,14 +3,19 @@ module Sequel
   # so they can be loaded via Model.plugin.
   #
   # Plugins should be modules with one of the following conditions:
-  # * A singleton method named apply, which takes a model and 
-  #   additional arguments.
+  # * A singleton method named apply, which takes a model, 
+  #   additional arguments, and an optional block.  This is called
+  #   once, the first time the plugin is loaded, with the arguments
+  #   and block provide to the call to Model.plugin.
   # * A module inside the plugin module named InstanceMethods,
   #   which will be included in the model class.
   # * A module inside the plugin module named ClassMethods,
   #   which will extend the model class.
   # * A module inside the plugin module named DatasetMethods,
   #   which will extend the model's dataset.
+  # * A singleton method named configure, which takes a model, 
+  #   additional arguments, and an optional block.  This is called
+  #   every time the Model.plugin method is called.
   module Plugins
   end
   
@@ -20,32 +25,38 @@ module Sequel
     # require the plugin from either sequel/plugins/#{plugin} or
     # sequel_#{plugin}, and then attempt to load the module using a
     # the camelized plugin name under Sequel::Plugins.
-    def self.plugin(plugin, *args)
+    def self.plugin(plugin, *args, &blk)
       arg = args.first
-      block = lambda{arg}
+      block = args.length > 1 ? lambda{args} : lambda{arg}
       m = plugin.is_a?(Module) ? plugin : plugin_module(plugin)
-      if m.respond_to?(:apply)
-        m.apply(self, *args)
-      end
-      if m.const_defined?("InstanceMethods")
-        define_method(:"#{plugin}_opts", &block)
-        include(m::InstanceMethods)
-      end
-      if m.const_defined?("ClassMethods")
-        meta_def(:"#{plugin}_opts", &block)
-        extend(m::ClassMethods)
-      end
-      if m.const_defined?("DatasetMethods")
-        if @dataset
-          dataset.meta_def(:"#{plugin}_opts", &block)
-          dataset.extend(m::DatasetMethods)
+      unless @plugins.include?(m)
+        @plugins << m
+        m.apply(self, *args, &blk) if m.respond_to?(:apply)
+        if m.const_defined?("InstanceMethods")
+          define_method(:"#{plugin}_opts", &block)
+          include(m::InstanceMethods)
+        end
+        if m.const_defined?("ClassMethods")
+          meta_def(:"#{plugin}_opts", &block)
+          extend(m::ClassMethods)
+        end
+        if m.const_defined?("DatasetMethods")
+          if @dataset
+            dataset.meta_def(:"#{plugin}_opts", &block)
+            dataset.extend(m::DatasetMethods)
+          end
+          dataset_method_modules << m::DatasetMethods
+          meths = m::DatasetMethods.public_instance_methods.reject{|x| NORMAL_METHOD_NAME_REGEXP !~ x.to_s}
+          def_dataset_method(*meths) unless meths.empty?
         end
-        dataset_method_modules << m::DatasetMethods
-        def_dataset_method(*m::DatasetMethods.public_instance_methods.reject{|x| NORMAL_METHOD_NAME_REGEXP !~ x.to_s})
       end
+      m.configure(self, *args, &blk) if m.respond_to?(:configure)
     end
     
     module ClassMethods
+      # Array of plugins loaded by this class
+      attr_reader :plugins
+      
       private
   
       # Returns the new style location for the plugin name.

data/lib/sequel/plugins/caching.rb

@@ -18,7 +18,7 @@ module Sequel
     module Caching
       # Set the cache_store and cache_ttl attributes for the given model.
       # If the :ttl option is not given, 3600 seconds is the default.
-      def self.apply(model, store, opts={})
+      def self.configure(model, store, opts={})
         model.instance_eval do
           @cache_store = store
           @cache_ttl = opts[:ttl] || 3600
@@ -32,20 +32,6 @@ module Sequel
         
         # The time to live for the cache store, in seconds.
         attr_reader :cache_ttl
-    
-        # Check the cache before a database lookup unless a hash is supplied.
-        def [](*args)
-          args = args.first if (args.size == 1)
-          return super(args) if args.is_a?(Hash)
-          ck = cache_key(args)
-          if obj = @cache_store.get(ck)
-            return obj
-          end
-          if obj = super(args)
-            @cache_store.set(ck, obj, @cache_ttl)
-          end 
-          obj
-        end
 
         # Set the time to live for the cache store, in seconds (default is 3600, # so 1 hour).
         def set_cache_ttl(ttl)
@@ -75,6 +61,18 @@ module Sequel
         def cache_key(pk)
           "#{self}:#{Array(pk).join(',')}"
         end
+        
+        # Check the cache before a database lookup unless a hash is supplied.
+        def primary_key_lookup(pk)
+          ck = cache_key(pk)
+          if obj = @cache_store.get(ck)
+            return obj
+          end
+          if obj = super(pk)
+            @cache_store.set(ck, obj, @cache_ttl)
+          end 
+          obj
+        end
       end
 
       module InstanceMethods

data/lib/sequel/plugins/identity_map.rb

@@ -0,0 +1,107 @@
+module Sequel
+  module Plugins
+    # The identity_map plugin allows the user to create temporary identity maps
+    # via the with_identity_map method, which takes a block.  Inside the block,
+    # objects have a 1-1 correspondence with rows in the database.
+    # 
+    # For example, the following is true, and wouldn't be true if you weren't
+    # using the identity map:
+    #   Sequel::Model.with_identity_map do
+    #     Album.filter{(id > 0) & (id < 2)}.first.object_id == Album.first(:id=>1).object_id
+    #   end
+    #
+    # In additional to providing a 1-1 correspondence, the identity_map plugin
+    # also provides a cached looked up of records in two cases:
+    # * Model.[] (e.g. Album[1])
+    # * Model.many_to_one accessor methods (e.g. album.artist)
+    #
+    # If the object you are looking up using one of those two methods is already
+    # in the identity map, the record is returned without a database query being
+    # issued.
+    #
+    # Identity maps are thread-local and only presist for the duration of the block,
+    # so they should be should only be considered as a possible performance enhancer.
+    module IdentityMap
+      module ClassMethods
+        # Returns the current thread-local identity map.  Should be a hash if
+        # there is an active identity map, and nil otherwise.
+        def identity_map
+          Thread.current[:sequel_identity_map]
+        end
+        
+        # The identity map key for an object of the current class with the given pk.
+        # May not always be correct for a class which uses STI.
+        def identity_map_key(pk)
+          "#{self}:#{pk ? Array(pk).join(',') : "nil:#{rand}"}"
+        end
+        
+        # If the identity map is in use, check it for a current copy of the object.
+        # If a copy does not exist, create a new object and add it to the identity map.
+        # If a copy exists, add any values in the given row that aren't currently
+        # in the object to the object's values.  This allows you to only request
+        # certain fields in an initial query, make modifications to some of those
+        # fields and request other, potentially overlapping fields in a new query,
+        # and not have the second query override fields you modified.
+        def load(row)
+          return super unless idm = identity_map
+          if o = idm[identity_map_key(Array(primary_key).map{|x| row[x]})]
+            o.merge_db_update(row)
+          else
+            o = super
+            idm[identity_map_key(o.pk)] = o
+          end
+          o
+        end
+        
+        # Take a block and inside that block use an identity map to ensure a 1-1
+        # correspondence of objects to the database row they represent.
+        def with_identity_map
+          return yield if identity_map
+          begin
+            self.identity_map = {}
+            yield
+          ensure
+            self.identity_map = nil
+          end
+        end
+        
+        private
+
+        # Set the thread local identity map to the given value. 
+        def identity_map=(v) 
+          Thread.current[:sequel_identity_map] = v
+        end
+        
+        # Check the current identity map if it exists for the object with
+        # the matching pk.  If one is found, return it, otherwise call super.
+        def primary_key_lookup(pk)
+          (idm = identity_map and o = idm[identity_map_key(pk)]) ? o : super
+        end
+      end
+
+      module InstanceMethods
+        # Merge the current values into the values provided in the row, ensuring
+        # that current values are not overridden by new values.
+        def merge_db_update(row)
+          @values = row.merge(@values)
+        end
+
+        private
+        
+        # If the association is a many_to_one and it has a :key option and the
+        # key option has a value and the association uses the primary key of
+        # the associated class as the :primary_key option, check the identity
+        # map for the associated object and return it if present.
+        def _load_associated_objects(opts)
+          klass = opts.associated_class
+          if idm = model.identity_map and !opts.returns_array? and opts[:key] and pk = send(opts[:key]) and
+           opts[:primary_key] == klass.primary_key and o = idm[klass.identity_map_key(pk)]
+            o
+          else
+            super
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/lazy_attributes.rb

@@ -0,0 +1,65 @@
+module Sequel
+  module Plugins
+    # The lazy_attributes plugin allows users to easily set that some attributes
+    # should not be loaded by default when loading model objects.  If the attribute
+    # is needed after the instance has been retrieved, a database query is made to
+    # retreive the value of the attribute.
+    #
+    # This plugin depends on the identity_map and tactical_eager_loading plugin, and allows you to
+    # eagerly load lazy attributes for all objects retrieved with the current object.
+    # So the following code should issue one query to get the albums and one query to
+    # get the reviews for all of those albums:
+    #
+    #   Album.plugin :lazy_attributes, :review
+    #   Sequel::Model.with_identity_map do
+    #     Album.filter{id<100}.all do |a|
+    #       a.review
+    #     end
+    #   end
+    module LazyAttributes
+      # Tactical eager loading requires the tactical_eager_loading plugin
+      def self.apply(model, *attrs)
+        model.plugin :identity_map
+        model.plugin :tactical_eager_loading  
+      end
+      
+      # Set the attributes given as lazy attributes
+      def self.configure(model, *attrs)
+        model.lazy_attributes(*attrs) unless attrs.empty?
+      end
+      
+      module ClassMethods
+        # Remove the given attributes from the list of columns selected by default.
+        # For each attribute given, create an accessor method that allows a lazy
+        # lookup of the attribute.  Each attribute should be given as a symbol.
+        def lazy_attributes(*attrs)
+          set_dataset(dataset.select(*(columns - attrs)))
+          attrs.each do |a|
+            define_method(a) do
+              if !values.include?(a) && !new?
+                lazy_attribute_lookup(a)
+              else
+                super()
+              end
+            end
+          end
+        end
+      end
+
+      module InstanceMethods
+        private
+
+        # If the model was selected with other model objects, eagerly load the
+        # attribute for all of those objects.  If not, query the database for
+        # the attribute for just the current object.  Return the value of
+        # the attribute for the current object.
+        def lazy_attribute_lookup(a)
+          primary_key = model.primary_key
+          model.select(*(Array(primary_key) + [a])).filter(primary_key=>retrieved_with.map{|o| o.pk}.sql_array).all if model.identity_map && retrieved_with
+          values[a] = this.select(a).first[a] unless values.include?(a)
+          values[a]
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/many_through_many.rb

@@ -0,0 +1,188 @@
+module Sequel
+  module Plugins
+    # The many_through_many plugin allow you to create a association to multiple objects using multiple join tables.
+    # For example, assume the following associations:
+    #
+    #    Artist.many_to_many :albums
+    #    Album.many_to_many :tags
+    #
+    # The many_through_many plugin would allow this:
+    #
+    #    Artist.many_through_many :tags, [[:albums_artists, :artist_id, :album_id], [:albums, :id, :id], [:albums_tags, :album_id, :tag_id]]
+    #
+    # Which will give you the tags for all of the artist's albums.
+    #
+    # Here are some more examples:
+    #
+    #   # Same as Artist.many_to_many :albums
+    #   Artist.many_through_many :albums, [[:albums_artists, :artist_id, :album_id]]
+    #
+    #   # All artists that are associated to any album that this artist is associated to
+    #   Artist.many_through_many :artists, [[:albums_artists, :artist_id, :album_id], [:albums, :id, :id], [:albums_artists, :album_id, :artist_id]]
+    #
+    #   # All albums by artists that are associated to any album that this artist is associated to
+    #   Artist.many_through_many :artist_albums, [[:albums_artists, :artist_id, :album_id], [:albums, :id, :id], \
+    #    [:albums_artists, :album_id, :artist_id], [:artists, :id, :id], [:albums_artists, :artist_id, :album_id]], \
+    #    :class=>:Album
+    #
+    #   # All tracks on albums by this artist
+    #   Artist.many_through_many :tracks, [[:albums_artists, :artist_id, :album_id], [:albums, :id, :id]], \
+    #    :right_primary_key=>:album_id
+    module ManyThroughMany
+      # The AssociationReflection subclass for many_through_many associations.
+      class ManyThroughManyAssociationReflection < Sequel::Model::Associations::ManyToManyAssociationReflection
+        Sequel::Model::Associations::ASSOCIATION_TYPES[:many_through_many] = self
+
+        # The table containing the column to use for the associated key when eagerly loading
+        def associated_key_table
+          self[:associated_key_table] = self[:final_reverse_edge][:alias]
+        end
+
+        # The list of joins to use when eager graphing
+        def edges
+          self[:edges] || calculate_edges || self[:edges]
+        end
+
+        # Many through many associations don't have a reciprocal
+        def reciprocal
+          nil
+        end
+
+        # The list of joins to use when lazy loading or eager loading
+        def reverse_edges
+          self[:reverse_edges] || calculate_edges || self[:reverse_edges]
+        end
+
+        private
+
+        # Make sure to use unique table aliases when lazy loading or eager loading
+        def calculate_reverse_edge_aliases(reverse_edges)
+          aliases = [associated_class.table_name]
+          reverse_edges.each do |e|
+            table_alias = e[:table]
+            if aliases.include?(table_alias)
+              i = 0
+              table_alias = loop do
+                ta = :"#{table_alias}_#{i}"
+                break ta unless aliases.include?(ta)
+                i += 1
+              end
+            end
+            aliases.push(e[:alias] = table_alias)
+          end
+        end
+
+        # Transform the :through option into a list of edges and reverse edges to use to join tables when loading the association.
+        def calculate_edges
+          es = [{:left_table=>self[:model].table_name, :left_key=>self[:left_primary_key]}]
+          self[:through].each do |t|
+            es.last.merge!(:right_key=>t[:left], :right_table=>t[:table], :join_type=>t[:join_type]||self[:graph_join_type], :conditions=>(t[:conditions]||[]).to_a, :block=>t[:block])
+            es.last[:only_conditions] = t[:only_conditions] if t.include?(:only_conditions)
+            es << {:left_table=>t[:table], :left_key=>t[:right]}
+          end
+          es.last.merge!(:right_key=>right_primary_key, :right_table=>associated_class.table_name)
+          edges = es.map do |e| 
+            h = {:table=>e[:right_table], :left=>e[:left_key], :right=>e[:right_key], :conditions=>e[:conditions], :join_type=>e[:join_type], :block=>e[:block]}
+            h[:only_conditions] = e[:only_conditions] if e.include?(:only_conditions)
+            h
+          end
+          reverse_edges = es.reverse.map{|e| {:table=>e[:left_table], :left=>e[:left_key], :right=>e[:right_key]}}
+          reverse_edges.pop
+          calculate_reverse_edge_aliases(reverse_edges)
+          self[:final_edge] = edges.pop
+          self[:final_reverse_edge] = reverse_edges.pop
+          self[:edges] = edges
+          self[:reverse_edges] = reverse_edges
+          nil
+        end
+      end
+      module ClassMethods
+        # Create a many_through_many association.  Arguments:
+        # * name - Same as associate, the name of the association.
+        # * through - The tables and keys to join between the current table and the associated table.
+        #   Must be an array, with elements that are either 3 element arrays, or hashes with keys :table, :left, and :right.
+        #   The required entries in the array/hash are:
+        #   * :table (first array element) - The name of the table to join.
+        #   * :left (middle array element) - The key joining the table to the previous table
+        #   * :right (last array element) - The key joining the table to the next table
+        #   If a hash is provided, the following keys are respected when using eager_graph:
+        #   * :block - A proc to use as the block argument to join.
+        #   * :conditions - Extra conditions to add to the JOIN ON clause.  Must be a hash or array of two pairs.
+        #   * :join_type - The join type to use for the join, defaults to :left_outer.
+        #   * :only_conditions - Conditions to use for the join instead of the ones specified by the keys.
+        # * opts - The options for the associaion.  Takes the same options as associate, and supports these additional options:
+        #   * :left_primary_key - column in current table that the first :left option in through points to, as a symbol. Defaults to primary key of current table. 
+        #   * :right_primary_key - column in associated table that the final :right option in through points to, as a symbol. Defaults to primary key of the associated table.
+        #   * :uniq - Adds a after_load callback that makes the array of objects unique.
+        def many_through_many(name, through, opts={}, &block)
+          associate(:many_through_many, name, opts.merge(:through=>through), &block)
+        end 
+
+        private
+
+        # Create the association methods and :eager_loader and :eager_grapher procs.
+        def def_many_through_many(opts)
+          name = opts[:name]
+          model = self
+          opts[:read_only] = true
+          opts[:class_name] ||= camelize(singularize(name))
+          opts[:after_load].unshift(:array_uniq!) if opts[:uniq]
+          opts[:cartesian_product_number] ||= 2
+          opts[:through] = opts[:through].map do |e|
+            case e
+            when Array
+              raise(Error, "array elements of the through option/argument for many_through_many associations must have at least three elements") unless e.length == 3
+              {:table=>e[0], :left=>e[1], :right=>e[2]}
+            when Hash
+              raise(Error, "hash elements of the through option/argument for many_through_many associations must contain :table, :left, and :right keys") unless e[:table] && e[:left] && e[:right]
+              e
+            else
+              raise(Error, "the through option/argument for many_through_many associations must be an enumerable of arrays or hashes")
+            end
+          end
+
+          left_key = opts[:left_key] = opts[:through].first[:left]
+          left_pk = (opts[:left_primary_key] ||= self.primary_key)
+          opts[:dataset] ||= lambda do
+            ds = opts.associated_class
+            opts.reverse_edges.each{|t| ds = ds.join(t[:table], [[t[:left], t[:right]]], :table_alias=>t[:alias])}
+            ft = opts[:final_reverse_edge]
+            ds.join(ft[:table], [[ft[:left], ft[:right]], [left_key, send(left_pk)]], :table_alias=>ft[:alias])
+          end
+
+          left_key_alias = opts[:left_key_alias] ||= opts.default_associated_key_alias
+          opts[:eager_loader] ||= lambda do |key_hash, records, associations|
+            h = key_hash[left_pk]
+            records.each{|object| object.associations[name] = []}
+            ds = opts.associated_class 
+            opts.reverse_edges.each{|t| ds = ds.join(t[:table], [[t[:left], t[:right]]], :table_alias=>t[:alias])}
+            ft = opts[:final_reverse_edge]
+            ds = ds.join(ft[:table], [[ft[:left], ft[:right]], [left_key, h.keys]], :table_alias=>ft[:alias])
+            model.eager_loading_dataset(opts, ds, Array(opts.select), associations).all do |assoc_record|
+              next unless objects = h[assoc_record.values.delete(left_key_alias)]
+              objects.each{|object| object.associations[name].push(assoc_record)}
+            end
+          end
+
+          join_type = opts[:graph_join_type]
+          select = opts[:graph_select]
+          graph_block = opts[:graph_block]
+          only_conditions = opts[:graph_only_conditions]
+          use_only_conditions = opts.include?(:graph_only_conditions)
+          conditions = opts[:graph_conditions]
+          opts[:eager_grapher] ||= proc do |ds, assoc_alias, table_alias|
+            iq = table_alias
+            opts.edges.each do |t|
+              ds = ds.graph(t[:table], t.include?(:only_conditions) ? t[:only_conditions] : ([[t[:right], t[:left]]] + t[:conditions]), :select=>false, :table_alias=>ds.send(:eager_unique_table_alias, ds, t[:table]), :join_type=>t[:join_type], :implicit_qualifier=>iq, &t[:block])
+              iq = nil
+            end
+            fe = opts[:final_edge]
+            ds.graph(opts.associated_class, use_only_conditions ? only_conditions : ([[opts.right_primary_key, fe[:left]]] + conditions), :select=>select, :table_alias=>assoc_alias, :join_type=>join_type, &graph_block)
+          end
+
+          def_association_dataset_methods(opts)
+        end
+      end
+    end
+  end
+end