sequel 3.21.0 → 3.36.0

data/lib/sequel/plugins/dirty.rb

@@ -0,0 +1,214 @@
+module Sequel
+  module Plugins
+    # The dirty plugin makes Sequel save the initial value of
+    # a column when setting a new value for the column.  This
+    # makes it easier to see what changes were made to the object:
+    #
+    #   artist.name                   # => 'Foo'
+    #   artist.name = 'Bar'
+    #   artist.initial_value(:name)   # 'Foo'
+    #   artist.column_change(:name)   # ['Foo', 'Bar']
+    #   artist.column_changes         # {:name => ['Foo', 'Bar']}
+    #   artist.column_changed?(:name) # true
+    #   artist.reset_column(:name)
+    #   artist.name                   # => 'Foo'
+    #   artist.column_changed?(:name) # false
+    #
+    # It allows makes changed_columns more accurate in that it
+    # can detect when a the column value is changed and then
+    # changed back:
+    #
+    #   artist.name                   # => 'Foo'
+    #   artist.name = 'Bar'
+    #   artist.changed_columns        # => [:name]
+    #   artist.name = 'Foo'
+    #   artist.changed_columns        # => []
+    #
+    # It can handle situations where a column value is
+    # modified in place:
+    #
+    #   artist.will_change_column(:name)
+    #   artist.name.gsub!(/o/, 'u')
+    #   artist.changed_columns       # => [:name]
+    #   artist.initial_value(:name)  # => 'Foo'
+    #   artist.column_change(:name)  # => ['Foo', 'Fuu']
+    #
+    # It also saves the previously changed values after an update:
+    #
+    #   artist.update(:name=>'Bar')
+    #   artist.column_changes        # => {}
+    #   artist.previous_changes      # => {:name=>['Foo', 'Bar']}
+    # 
+    # Usage:
+    #
+    #   # Make all model subclass instances record previous values (called before loading subclasses)
+    #   Sequel::Model.plugin :dirty
+    #
+    #   # Make the Album class record previous values
+    #   Album.plugin :dirty
+    module Dirty
+      module InstanceMethods
+        # A hash of previous changes before the object was
+        # saved, in the same format as #column_changes.
+        # Note that this is not necessarily the same as the columns
+        # that were used in the update statement.
+        attr_reader :previous_changes
+
+        # An array with the initial value and the current value
+        # of the column, if the column has been changed.  If the
+        # column has not been changed, returns nil.
+        #
+        #   column_change(:name) # => ['Initial', 'Current']
+        def column_change(column)
+          [initial_value(column), send(column)] if column_changed?(column)
+        end
+
+        # A hash with column symbol keys and pairs of initial and
+        # current values for all changed columns.
+        #
+        #   column_changes # => {:name => ['Initial', 'Current']}
+        def column_changes
+          h = {}
+          initial_values.each do |column, value|
+            h[column] = [value, send(column)]
+          end
+          h
+        end
+
+        # Either true or false depending on whether the column has
+        # changed.  Note that this is not exactly the same as checking if
+        # the column is in changed_columns, if the column was not set
+        # initially.
+        #
+        #   column_changed?(:name) # => true
+        def column_changed?(column)
+          initial_values.has_key?(column)
+        end
+
+        # The initial value of the given column.  If the column value has
+        # not changed, this will be the same as the current value of the
+        # column.
+        #
+        #   initial_value(:name) # => 'Initial'
+        def initial_value(column)
+          initial_values.fetch(column){send(column)}
+        end
+
+        # A hash with column symbol keys and initial values.
+        #
+        #   initial_values # {:name => 'Initial'}
+        def initial_values
+          @initial_values ||= {}
+        end
+
+        # Reset the column to its initial value.  If the column was not set
+        # initial, removes it from the values.
+        #
+        #   reset_column(:name)
+        #   name # => 'Initial'
+        def reset_column(column)
+          if initial_values.has_key?(column)
+            send(:"#{column}=", initial_values[column])
+          end
+          if missing_initial_values.include?(column)
+            values.delete(column)
+          end
+        end
+
+        # Manually specify that a column will change.  This should only be used
+        # if you plan to modify a column value in place, which is not recommended.
+        #
+        #   will_change_column(:name)
+        #   name.gsub(/i/i, 'o')
+        #   column_change(:name) # => ['Initial', 'onotoal']
+        def will_change_column(column)
+          changed_columns << column unless changed_columns.include?(column)
+          check_missing_initial_value(column)
+
+          value = if initial_values.has_key?(column)
+            initial_values[column]
+          else
+            send(column)
+          end
+
+          initial_values[column] = if value && value != true && value.respond_to?(:clone)
+            begin
+              value.clone
+            rescue TypeError
+              value
+            end
+          else
+            value
+          end
+        end
+
+        private
+
+        # Reset the initial values after saving.
+        def after_save
+          super
+          reset_initial_values
+        end
+
+        # Save the current changes so they are available after updating.  This happens
+        # before after_save resets them.
+        def after_update
+          super
+          @previous_changes = column_changes
+        end
+
+        # Reset the initial values when refreshing.
+        def _refresh(dataset)
+          super
+          reset_initial_values
+        end
+
+        # When changing the column value, save the initial column value.  If the column
+        # value is changed back to the initial value, update changed columns to remove
+        # the column.
+        def change_column_value(column, value)
+          if (iv = initial_values).has_key?(column)
+            initial = iv[column]
+            super
+            if value == initial
+              changed_columns.delete(column) unless missing_initial_values.include?(column)
+              iv.delete(column)
+            end
+          else
+            check_missing_initial_value(column)
+            iv[column] = send(column)
+            super
+          end
+        end
+
+        # If the values hash does not contain the column, make sure missing_initial_values
+        # does so that it doesn't get deleted from changed_columns if changed back,
+        # and so that reseting the column value can be handled correctly.
+        def check_missing_initial_value(column)
+          unless values.has_key?(column) || (miv = missing_initial_values).include?(column)
+            miv << column
+          end
+        end
+
+        # Reset the initial values when initializing.
+        def initialize_set(h)
+          super
+          reset_initial_values
+        end
+
+        # Array holding column symbols that were not present initially.  This is necessary
+        # to differentiate between values that were not present and values that were
+        # present but equal to nil.
+        def missing_initial_values
+          @missing_initial_values ||= []
+        end
+
+        # Clear the data structures that store the initial values.
+        def reset_initial_values
+          @initial_values.clear if @initial_values
+          @missing_initial_values.clear if @missing_initial_values
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/eager_each.rb

@@ -0,0 +1,59 @@
+module Sequel
+  module Plugins
+    # The eager_each plugin makes calling each on an eager loaded dataset do eager loading.
+    # By default, each does not work on an eager loaded dataset, because each iterates
+    # over rows of the dataset as they come in, and to eagerly load you need to have all
+    # values up front.  With the default associations code, you must call #all on an eagerly
+    # loaded dataset, as calling #each on an #eager dataset skips the eager loading, and calling
+    # #each on an #eager_graph dataset makes it yield plain hashes with columns from all
+    # tables, instead of yielding the instances of the main model.
+    #
+    # This plugin makes #each call #all for eagerly loaded datasets.  As #all usually calls
+    # #each, this is a bit of issue, but this plugin resolves the issue by cloning the dataset
+    # and setting a new flag in the cloned dataset, so that each can check with the flag to
+    # determine whether it should call all.
+    # 
+    # Usage:
+    #
+    #   # Make all model subclass instances eagerly load for each (called before loading subclasses)
+    #   Sequel::Model.plugin :eager_each
+    #
+    #   # Make the Album class eagerly load for each
+    #   Album.plugin :eager_each
+    module EagerEach 
+      # Methods added to eagerly loaded datasets when the eager_each plugin is in use.
+      module EagerDatasetMethods
+        # Call #all instead of #each unless #each is being called by #all.
+        def each(&block)
+          if opts[:all_called]
+            super
+          else
+            all(&block)
+          end
+        end
+
+        # Clone the dataset and set a flag to let #each know not to call #all,
+        # to avoid the infinite loop.
+        def all(&block)
+          if opts[:all_called]
+            super
+          else
+            clone(:all_called=>true).all(&block)
+          end
+        end
+      end
+
+      module DatasetMethods
+        # Make sure calling each on this dataset will eagerly load the dataset.
+        def eager(*)
+          super.extend(EagerDatasetMethods)
+        end
+        
+        # Make sure calling each on this dataset will eagerly load the dataset.
+        def eager_graph(*)
+          super.extend(EagerDatasetMethods)
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/force_encoding.rb

@@ -8,7 +8,7 @@ module Sequel
     # attribute, the resulting value is forced to a given encoding if the
     # value is a string.  There are two ways to specify the encoding.  You
     # can either do so in the plugin call itself, or via the
-    # forced_encoding class accessor:
+    # forced_encoding class accessor.
     #
     # Usage:
     #
@@ -46,6 +46,11 @@ module Sequel
           super(force_hash_encoding(row))
         end
         
+        # Force the encoding of all string values when setting the instance's values.
+        def set_values(row)
+          super(force_hash_encoding(row))
+        end
+        
         private
         
         # Force the encoding for all string values in the given row hash.
@@ -55,11 +60,6 @@ module Sequel
           row
         end
         
-        # Force the encoding of all string values when setting the instance's values.
-        def set_values(row)
-          super(force_hash_encoding(row))
-        end
-        
         # Force the encoding of all returned strings to the model's forced_encoding.
         def typecast_value(column, value)
           s = super

data/lib/sequel/plugins/hook_class_methods.rb

@@ -90,9 +90,9 @@ module Sequel
 
         # Make a copy of the current class's hooks for the subclass.
         def inherited(subclass)
-          super
           hooks = subclass.instance_variable_set(:@hooks, {}) 
           instance_variable_get(:@hooks).each{|k,v| hooks[k] = v.dup}
+          super
         end
     
         private

data/lib/sequel/plugins/identity_map.rb

@@ -22,10 +22,7 @@ module Sequel
     # Identity maps are thread-local and only persist for the duration of the block,
     # so they should only be considered as a possible performance enhancer.
     #
-    # The identity_map plugin is not compatible with the standard eager loading of
-    # many_to_many and many_through_many associations.  If you want to use the identity_map plugin,
-    # you should use +eager_graph+ instead of +eager+ for those associations. It is also
-    # not compatible with the eager loading in the +rcte_tree+ plugin.
+    # The identity_map plugin is not compatible with the eager loading in the +rcte_tree+ plugin.
     #
     # Usage:
     #
@@ -37,6 +34,116 @@ module Sequel
     #   # would need to do Album.with_identity_map{} to use the identity map
     module IdentityMap
       module ClassMethods
+        # Override the default :eager_loader option for many_*_many associations to work
+        # with an identity_map.  If the :eager_graph association option is used, you'll probably have to use
+        # :uniq=>true on the current association amd :cartesian_product_number=>2 on the association
+        # mentioned by :eager_graph, otherwise you'll end up with duplicates because the row proc will be
+        # getting called multiple times for the same object.  If you do have duplicates and you use :eager_graph,
+        # they'll probably be lost.  Making that work correctly would require changing a lot of the core
+        # architecture, such as how graphing and eager graphing work.
+        def associate(type, name, opts = {}, &block)
+          if opts[:eager_loader]
+            super
+          elsif type == :many_to_many
+            opts = super
+            el = opts[:eager_loader] 
+            model = self
+            left_pk = opts[:left_primary_key]
+            uses_lcks = opts[:uses_left_composite_keys]
+            uses_rcks = opts[:uses_right_composite_keys]
+            right = opts[:right_key]
+            join_table = opts[:join_table]
+            left = opts[:left_key]
+            lcks = opts[:left_keys]
+            left_key_alias = opts[:left_key_alias] ||= opts.default_associated_key_alias
+            opts[:eager_loader] = lambda do |eo|
+              return el.call(eo) unless model.identity_map
+              h = eo[:key_hash][left_pk]
+              eo[:rows].each{|object| object.associations[name] = []}
+              r = uses_rcks ? rcks.zip(opts.right_primary_keys) : [[right, opts.right_primary_key]]
+              l = uses_lcks ? [[lcks.map{|k| SQL::QualifiedIdentifier.new(join_table, k)}, h.keys]] : [[left, h.keys]]
+
+              # Replace the row proc to remove the left key alias before calling the previous row proc.
+              # Associate the value of the left key alias with the associated object (through its object_id).
+              # When loading the associated objects, lookup the left key alias value and associate the
+              # associated objects to the main objects if the left key alias value matches the left primary key
+              # value of the main object.
+              # 
+              # The deleting of the left key alias from the hash before calling the previous row proc
+              # is necessary when an identity map is used, otherwise if the same associated object is returned more than
+              # once for the association, it won't know which of current objects to associate it to.
+              ds = opts.associated_class.inner_join(join_table, r + l)
+              pr = ds.row_proc
+              h2 = {}
+              ds.row_proc = proc do |hash|
+                hash_key = if uses_lcks
+                  left_key_alias.map{|k| hash.delete(k)}
+                else
+                  hash.delete(left_key_alias)
+                end
+                obj = pr.call(hash)
+                (h2[obj.object_id] ||= []) << hash_key
+                obj
+              end
+              model.eager_loading_dataset(opts, ds, Array(opts.select), eo[:associations], eo) .all do |assoc_record|
+                if hash_keys = h2.delete(assoc_record.object_id)
+                  hash_keys.each do |hash_key|
+                    if objects = h[hash_key]
+                      objects.each{|object| object.associations[name].push(assoc_record)}
+                    end
+                  end
+                end
+              end
+            end
+            opts
+          elsif type == :many_through_many
+            opts = super
+            el = opts[:eager_loader] 
+            model = self
+            left_pk = opts[:left_primary_key]
+            left_key = opts[:left_key]
+            uses_lcks = opts[:uses_left_composite_keys]
+            left_keys = Array(left_key)
+            left_key_alias = opts[:left_key_alias]
+            opts[:eager_loader] = lambda do |eo|
+              return el.call(eo) unless model.identity_map
+              h = eo[:key_hash][left_pk]
+              eo[:rows].each{|object| object.associations[name] = []}
+              ds = opts.associated_class 
+              opts.reverse_edges.each{|t| ds = ds.join(t[:table], Array(t[:left]).zip(Array(t[:right])), :table_alias=>t[:alias])}
+              ft = opts.final_reverse_edge
+              conds = uses_lcks ? [[left_keys.map{|k| SQL::QualifiedIdentifier.new(ft[:table], k)}, h.keys]] : [[left_key, h.keys]]
+
+              # See above comment in many_to_many eager_loader
+              ds = ds.join(ft[:table], Array(ft[:left]).zip(Array(ft[:right])) + conds, :table_alias=>ft[:alias])
+              pr = ds.row_proc
+              h2 = {}
+              ds.row_proc = proc do |hash|
+                hash_key = if uses_lcks
+                  left_key_alias.map{|k| hash.delete(k)}
+                else
+                  hash.delete(left_key_alias)
+                end
+                obj = pr.call(hash)
+                (h2[obj.object_id] ||= []) << hash_key
+                obj
+              end
+              model.eager_loading_dataset(opts, ds, Array(opts.select), eo[:associations], eo).all do |assoc_record|
+                if hash_keys = h2.delete(assoc_record.object_id)
+                  hash_keys.each do |hash_key|
+                    if objects = h[hash_key]
+                      objects.each{|object| object.associations[name].push(assoc_record)}
+                    end
+                  end
+                end
+              end
+            end
+            opts
+          else
+            super
+          end
+        end
+          
         # Returns the current thread-local identity map.  Should be a hash if
         # there is an active identity map, and nil otherwise.
         def identity_map
@@ -56,7 +163,7 @@ module Sequel
         # 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)
+        def call(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)
@@ -121,10 +228,18 @@ module Sequel
         # 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)
+        def _load_associated_object(opts, dynamic_opts)
           klass = opts.associated_class
-          if klass.respond_to?(:identity_map) && idm = klass.identity_map and opts[:type] == :many_to_one and opts[:primary_key] == klass.primary_key and
-           opts[:key] and pk = _associated_object_pk(opts[:key]) and o = idm[klass.identity_map_key(pk)]
+          cache_lookup = opts.fetch(:idm_cache_lookup) do 
+            opts[:idm_cache_lookup] = klass.respond_to?(:identity_map) &&
+              opts[:type] == :many_to_one &&
+              opts[:key] &&
+              opts.primary_key == klass.primary_key
+          end
+          if cache_lookup &&
+            !dynamic_opts[:callback] &&
+            (idm = klass.identity_map) &&
+            (o = idm[klass.identity_map_key(_associated_object_pk(opts[:key]))])
             o
           else
             super

data/lib/sequel/plugins/instance_filters.rb

@@ -68,6 +68,16 @@ module Sequel
       
         private
         
+        # If there are any instance filters, make sure not to use the
+        # instance delete optimization.
+        def _delete_without_checking
+          if @instance_filters && !@instance_filters.empty?
+            _delete_dataset.delete 
+          else
+            super
+          end
+        end
+
         # Lazily initialize the instance filter array.
         def instance_filters
           @instance_filters ||= []

data/lib/sequel/plugins/instance_hooks.rb

@@ -29,7 +29,7 @@ module Sequel
         BEFORE_HOOKS = Sequel::Model::BEFORE_HOOKS
         AFTER_HOOKS = Sequel::Model::AFTER_HOOKS - [:after_initialize]
         HOOKS = BEFORE_HOOKS + AFTER_HOOKS
-        HOOKS.each{|h| class_eval("def #{h}_hook(&block); add_instance_hook(:#{h}, &block) end", __FILE__, __LINE__)}
+        HOOKS.each{|h| class_eval("def #{h}_hook(&block); add_instance_hook(:#{h}, &block); self end", __FILE__, __LINE__)}
         
         BEFORE_HOOKS.each{|h| class_eval("def #{h}; run_before_instance_hooks(:#{h}) == false ? false : super end", __FILE__, __LINE__)}
         AFTER_HOOKS.each{|h| class_eval(<<-END, __FILE__, __LINE__ + 1)}

data/lib/sequel/plugins/json_serializer.rb

@@ -56,6 +56,11 @@ module Sequel
     #   Album.to_json
     #   Album.filter(:artist_id=>1).to_json(:include=>:tags)
     #
+    # If you have an existing array of model instances you want to convert to
+    # JSON, you can call the class to_json method with the :array option:
+    #
+    #   Album.to_json(:array=>[Album[1], Album[2]])
+    #
     # Usage:
     #
     #   # Add JSON output capability to all model subclass instances (called before loading subclasses)
@@ -134,8 +139,13 @@ module Sequel
       module InstanceMethods
         # Parse the provided JSON, which should return a hash,
         # and call +set+ with that hash.
-        def from_json(json)
-          set(JSON.parse(json))
+        def from_json(json, opts={})
+          h = JSON.parse(json)
+          if fields = opts[:fields]
+            set_fields(h, fields, opts)
+          else
+            set(h)
+          end
         end
 
         # Return a string in JSON format.  Accepts the following
@@ -149,7 +159,7 @@ module Sequel
         #             to include in the JSON output.  Using a nested
         #             hash, you can pass options to associations
         #             to affect the JSON used for associated objects.
-        # :naked :: Not to add the JSON.create_id key to the JSON
+        # :naked :: Not to add the JSON.create_id (json_class) key to the JSON
         #           output hash, so when the JSON is parsed, it
         #           will yield a hash instead of a model object.
         # :only :: Symbol or Array of Symbols of columns to only
@@ -195,7 +205,21 @@ module Sequel
       module DatasetMethods
         # Return a JSON string representing an array of all objects in
         # this dataset.  Takes the same options as the the instance
-        # method, and passes them to every instance.
+        # method, and passes them to every instance.  Additionally,
+        # respects the following options:
+        #
+        # :array :: An array of instances.  If this is not provided,
+        #           calls #all on the receiver to get the array.
+        # :root :: If set to :collection, only wraps the collection
+        #          in a root object.  If set to :instance, only wraps
+        #          the instances in a root object.  If set to :both,
+        #          wraps both the collection and instances in a root
+        #          object.  Unfortunately, for backwards compatibility,
+        #          if this option is true and doesn't match one of those
+        #          symbols, it defaults to both.  That may change in a
+        #          future version, so for forwards compatibility, you
+        #          should pick a specific symbol for your desired
+        #          behavior.
         def to_json(*a)
           if opts = a.first.is_a?(Hash)
             opts = model.json_serializer_opts.merge(a.first)
@@ -203,8 +227,36 @@ module Sequel
           else
             opts = model.json_serializer_opts
           end
-          res = row_proc ? all.map{|obj| Literal.new(obj.to_json(opts))} : all
-          opts[:root] ? {model.send(:pluralize, model.send(:underscore, model.to_s)) => res}.to_json(*a) : res.to_json(*a)
+
+          collection_root = case opts[:root]
+          when nil, false, :instance
+            false
+          when :collection
+            opts = opts.dup
+            opts.delete(:root)
+            opts[:naked] = true unless opts.has_key?(:naked)
+            true
+          else
+            true
+          end
+
+          res = if row_proc 
+            array = if opts[:array]
+              opts = opts.dup
+              opts.delete(:array)
+            else
+              all
+            end
+            array.map{|obj| Literal.new(obj.to_json(opts))}
+           else
+            all
+          end
+
+          if collection_root
+            {model.send(:pluralize, model.send(:underscore, model.to_s)) => res}.to_json(*a)
+          else
+            res.to_json(*a)
+          end
         end
       end
     end

data/lib/sequel/plugins/list.rb

@@ -39,9 +39,11 @@ module Sequel
     #   Item.plugin :list, :scope=>:user_id
     # 
     # Note that using this plugin modifies the order of the model's dataset to
-    # sort by the position and scope fields.
+    # sort by the position and scope fields.  Also note that this plugin is subject to
+    # race conditions, and is not safe when concurrent modifications are made
+    # to the same list.
     #
-    # Also note that unlike ruby arrays, the list plugin assumes that the
+    # Additionally, note that unlike ruby arrays, the list plugin assumes that the
     # first entry in the list has position 1, not position 0.
     #
     # Copyright (c) 2007-2010 Sharon Rosner, Wayne E. Seguin, Aman Gupta, Adrian Madrid, Jeremy Evans
@@ -90,6 +92,14 @@ module Sequel
           list_dataset.first(position_field => p)
         end
 
+        # Set the value of the position_field to the maximum value plus 1 unless the
+        # position field already has a value.
+        def before_create
+          unless send(position_field)
+            send("#{position_field}=", list_dataset.max(position_field).to_i+1)
+          end
+        end
+
         # Find the last position in the list containing this instance.
         def last_position
           list_dataset.max(position_field).to_i