sequel 3.21.0 → 3.31.0

data/lib/sequel/plugins/serialization.rb

@@ -11,8 +11,17 @@ module Sequel
     # set the @deserialized_values entry.  This plugin adds a before_save hook
     # that serializes all @deserialized_values to @values.
     #
-    # You can use either marshal, yaml, or json as the serialization format.
-    # If you use yaml or json, you should require them by yourself.
+    # You can specify the serialization format as a pair of serializer/deserializer
+    # callable objects.  You can also specify the serialization format as a single
+    # symbol, if such a symbol has a registered serializer/deserializer pair in the
+    # plugin.  By default, the plugin registers the :marshal, :yaml, and :json
+    # serialization formats.  To register your own serialization formats, use
+    # Sequel::Plugins::Serialization.register_format.
+    # If you use yaml or json format, you need to require the libraries, Sequel
+    # does not do the requiring for you.
+    #
+    # You can specify the columns to serialize when loading the plugin, or later
+    # using the serialize_attributes class method.
     #
     # Because of how this plugin works, it must be used inside each model class
     # that needs serialization, after any set_dataset method calls in that class.
@@ -22,56 +31,96 @@ module Sequel
     # == Example
     #
     #   require 'sequel'
+    #   # Require json, as the plugin doesn't require it for you.
     #   require 'json'
+    #
+    #   # Register custom serializer/deserializer pair
+    #   Sequel::Plugins::Serialization.register_format(:reverse,
+    #     lambda{|v| v.reverse},
+    #     lambda{|v| v.reverse})
+    #
     #   class User < Sequel::Model
+    #     # Built-in format support when loading the plugin
     #     plugin :serialization, :json, :permissions
-    #     # or
+    #
+    #     # Built-in format support after loading the plugin using serialize_attributes
     #     plugin :serialization
-    #     serialize_attributes :marshal, :permissions, :attributes
+    #     serialize_attributes :marshal, :permissions
+    #
+    #     # Use custom registered serialization format just like built-in format
+    #     serialize_attributes :reverse, :password
+    #
+    #     # Use a custom serializer/deserializer pair without registering
+    #     serialize_attributes [lambda{|v| v.reverse}, lambda{|v| v.reverse}], :password
     #   end
     #   user = User.create
     #   user.permissions = { :global => 'read-only' }
     #   user.save
     module Serialization
+      # The default serializers supported by the serialization module.
+      # Use register_format to add serializers to this hash.
+      REGISTERED_FORMATS = {}
+
       # Set up the column readers to do deserialization and the column writers
       # to save the value in deserialized_values.
       def self.apply(model, *args)
-        model.instance_eval{@serialization_map = {}}
+        model.instance_eval do
+          @deserialization_map = {}
+          @serialization_map = {}
+        end
       end
       
+      # Automatically call serialize_attributes with the format and columns unless
+      # no columns were provided.
       def self.configure(model, format=nil, *columns)
         model.serialize_attributes(format, *columns) unless columns.empty?
       end
 
+      # Register a serializer/deserializer pair with a format symbol, to allow
+      # models to pick this format by name.  Both serializer and deserializer
+      # should be callable objects.
+      def self.register_format(format, serializer, deserializer)
+        REGISTERED_FORMATS[format] = [serializer, deserializer]
+      end
+      register_format(:marshal, lambda{|v| [Marshal.dump(v)].pack('m')}, lambda{|v| Marshal.load(v.unpack('m')[0]) rescue Marshal.load(v)})
+      register_format(:yaml, lambda{|v| v.to_yaml}, lambda{|v| YAML.load(v)})
+      register_format(:json, lambda{|v| v.to_json}, lambda{|v| JSON.parse(v)})
+
       module ClassMethods
-        # A map of the serialized columns for this model.  Keys are column
-        # symbols, values are serialization formats (:marshal, :yaml, or :json).
+        # A hash with column name symbols and callable values, with the value
+        # called to deserialize the column.
+        attr_reader :deserialization_map
+
+        # A hash with column name symbols and callable values, with the value
+        # called to serialize the column.
         attr_reader :serialization_map
 
         # Module to store the serialized column accessor methods, so they can
         # call be overridden and call super to get the serialization behavior
         attr_accessor :serialization_module
 
-        # Copy the serialization format and columns to serialize into the subclass.
+        # Copy the serialization_map and deserialization map into the subclass.
         def inherited(subclass)
           super
           sm = serialization_map.dup
-          subclass.instance_eval{@serialization_map = sm}
-        end
-        
-        # The first value in the serialization map.  This is only for
-        # backwards compatibility, use serialization_map in new code.
-        def serialization_format
-          serialization_map.values.first
+          dsm = deserialization_map.dup
+          subclass.instance_eval do
+            @deserialization_map = dsm
+            @serialization_map = sm
+          end
         end
         
         # Create instance level reader that deserializes column values on request,
-        # and instance level writer that stores new deserialized value in deserialized
-        # columns
+        # and instance level writer that stores new deserialized values.
         def serialize_attributes(format, *columns)
-          raise(Error, "Unsupported serialization format (#{format}), should be :marshal, :yaml, or :json") unless [:marshal, :yaml, :json].include?(format)
+          if format.is_a?(Symbol)
+            unless format = REGISTERED_FORMATS[format]
+              raise(Error, "Unsupported serialization format: #{format} (valid formats: #{REGISTERED_FORMATS.keys.map{|k| k.inspect}.join})")
+            end
+          end
+          serializer, deserializer = format
           raise(Error, "No columns given.  The serialization plugin requires you specify which columns to serialize") if columns.empty?
-          define_serialized_attribute_accessor(format, *columns)
+          define_serialized_attribute_accessor(serializer, deserializer, *columns)
         end
         
         # The columns that will be serialized.  This is only for
@@ -83,12 +132,13 @@ module Sequel
         private
 
         # Add serializated attribute acessor methods to the serialization_module
-        def define_serialized_attribute_accessor(format, *columns)
+        def define_serialized_attribute_accessor(serializer, deserializer, *columns)
           m = self
           include(self.serialization_module ||= Module.new) unless serialization_module
           serialization_module.class_eval do
             columns.each do |column|
-              m.serialization_map[column] = format
+              m.serialization_map[column] = serializer
+              m.deserialization_map[column] = deserializer
               define_method(column) do 
                 if deserialized_values.has_key?(column)
                   deserialized_values[column]
@@ -110,7 +160,7 @@ module Sequel
         attr_reader :deserialized_values
 
         # Set @deserialized_values to the empty hash
-        def initialize(*args, &block)
+        def initialize_set(values)
           @deserialized_values = {}
           super
         end
@@ -127,35 +177,29 @@ module Sequel
           super
         end
 
+        # Initialization the deserialized values for objects retrieved from the database.
+        def set_values(*)
+          @deserialized_values ||= {}
+          super
+        end
+
         private
 
-        # Deserialize the column from either marshal or yaml format
+        # Deserialize the column value.  Called when the model column accessor is called to
+        # return a deserialized value.
         def deserialize_value(column, v)
-          return v if v.nil?
-          case model.serialization_map[column] 
-          when :marshal
-            Marshal.load(v.unpack('m')[0]) rescue Marshal.load(v)
-          when :yaml
-            YAML.load v if v
-          when :json
-            JSON.parse v if v
-          else
-            raise Error, "Bad serialization format (#{model.serialization_map[column].inspect}) for column #{column.inspect}"
+          unless v.nil?
+            raise Sequel::Error, "no entry in deserialization_map for #{column.inspect}" unless callable = model.deserialization_map[column]
+            callable.call(v)
           end
         end
 
-        # Serialize the column to either marshal or yaml format
+        # Serialize the column value.  Called before saving to ensure the serialized value
+        # is saved in the database.
         def serialize_value(column, v)
-          return v if v.nil?
-          case model.serialization_map[column] 
-          when :marshal
-            [Marshal.dump(v)].pack('m')
-          when :yaml
-            v.to_yaml
-          when :json
-            v.to_json
-          else
-            raise Error, "Bad serialization format (#{model.serialization_map[column].inspect}) for column #{column.inspect}"
+          unless v.nil?
+            raise Sequel::Error, "no entry in serialization_map for #{column.inspect}" unless callable = model.serialization_map[column]
+            callable.call(v)
           end
         end
       end

data/lib/sequel/plugins/serialization_modification_detection.rb

@@ -0,0 +1,51 @@
+module Sequel
+  module Plugins
+    # Sequel's built in Serialization plugin doesn't check for modification
+    # of the serialized objects, because it requires an extra deserialization of a potentially
+    # very large object.  This plugin can detect changes in serialized values by
+    # checking whether the current deserialized value is the same as the original
+    # deserialized value.  This does require deserializing the value twice, but the
+    # original deserialized value is cached.
+    #
+    # == Example
+    #
+    #   require 'sequel'
+    #   require 'json'
+    #   class User < Sequel::Model
+    #     plugin :serialization, :json, :permissions
+    #     plugin :serialization_modification_detection
+    #   end
+    #   user = User.create(:permissions => {})
+    #   user.permissions[:global] = 'read-only'
+    #   user.save_changes
+    module SerializationModificationDetection
+      # Load the serialization plugin automatically.
+      def self.apply(model)
+        model.plugin :serialization
+      end
+      
+      module InstanceMethods
+        # Detect which serialized columns have changed.
+        def changed_columns
+          cc = super
+          deserialized_values.each{|c, v| cc << c if !cc.include?(c) && original_deserialized_value(c) != v} 
+          cc
+        end
+
+        private
+
+        # Clear the cache of original deserialized values after saving so that it doesn't
+        # show the column is modified after saving.
+        def after_save
+          super
+          @original_deserialized_values.clear if @original_deserialized_values
+        end
+
+        # Return the original deserialized value of the column, caching it to improve performance.
+        def original_deserialized_value(column)
+          (@original_deserialized_values ||= {})[column] ||= deserialize_value(column, self[column])
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/sharding.rb

@@ -1,13 +1,14 @@
 module Sequel
   module Plugins
-    # The sharding plugin makes it easy to use Sequel's sharding features
-    # with models.  It lets you create model objects on specific shards,
-    # and any models retrieved from specific shards are automatically
-    # saved back to those shards.  It also works with associations,
-    # so that model objects retrieved from specific shards will only
-    # return associated objects from that shard, and using the
-    # add/remove/remove_all association methods will only affect
-    # that shard.
+    # The sharding plugin augments Sequel's default model sharding support
+    # in the following ways:
+    #
+    # 1) It automatically sets model instances to be saved back to the
+    #    shard they were retreived from.
+    # 2) It makes model associations use the same shard as the model
+    #    object.
+    # 3) It adds a slightly nicer API for creating model instances on
+    #    specific shards.
     # 
     # Usage:
     #
@@ -40,15 +41,21 @@ module Sequel
         def new_using_server(s, values={}, &block)
           new(values, &block).set_server(s)
         end
-      end
 
-      module InstanceMethods
-        # Set the shard that this object is tied to.  Returns self.
-        def set_server(s)
-          @server = s
-          self
+        private
+
+        # Set the server for each graphed dataset to the current server
+        # unless the graphed dataset already has a server set.
+        def eager_graph_dataset(opts, eager_options)
+          ds = super
+          if s = eager_options[:self].opts[:server]
+            ds = ds.server(s) unless ds.opts[:server]
+          end
+          ds
         end
+      end
 
+      module InstanceMethods
         # Set the server that this object is tied to, unless it has
         # already been set.  Returns self.
         def set_server?(s)
@@ -56,11 +63,6 @@ module Sequel
           self
         end
 
-        # Ensure that the instance dataset is tied to the correct shard.
-        def this
-          use_server(super)
-        end
-
         private
 
         # Ensure that association datasets are tied to the correct shard.
@@ -68,21 +70,11 @@ module Sequel
           use_server(super)
         end
 
-        # Ensure that the object is inserted into the correct shard.
-        def _insert_dataset
-          use_server(super)
-        end
-
         # Ensure that the join table for many_to_many associations uses the correct shard.
         def _join_table_dataset(opts)
           use_server(super)
         end
 
-        # Make sure to use the correct shard when using a transaction
-        def checked_transaction(opts={}, &block)
-          super(@server ? {:server=>@server}.merge(opts) : opts, &block)
-        end
-
         # If creating the object by doing <tt>add_association</tt> for a
         # +many_to_many+ association, make sure the associated object is created on the
         # current object's shard, unless the passed object already has an assigned shard.
@@ -90,11 +82,6 @@ module Sequel
           o.set_server?(@server) if o.respond_to?(:set_server?)
           super
         end
-
-        # Set the given dataset to use the current object's shard.
-        def use_server(ds)
-          @server ? ds.server(@server) : ds
-        end
       end
 
       module DatasetMethods
@@ -109,26 +96,6 @@ module Sequel
           end
           ds
         end
-
-        private
-
-        # Set the shard of all retrieved objects to the shard of
-        # the table's dataset, or the current shard if the table's
-        # dataset does not have a shard.
-        def graph_each
-          ta = @opts[:graph][:table_aliases]
-          s = @opts[:server]
-          super do |r|
-            r.each do |k, v|
-              if ds = ta[k]
-                dss = ds.opts[:server]
-              end
-              vs = dss || s
-              v.set_server(vs) if vs && v.respond_to?(:set_server)
-            end
-            yield r
-          end
-        end
       end
     end
   end

data/lib/sequel/plugins/single_table_inheritance.rb

@@ -108,8 +108,10 @@ module Sequel
           key = skm[subclass] 
           sti_subclass_added(key)
           ska = [key]
+          rp = dataset.row_proc
           subclass.set_dataset(sd.filter(SQL::QualifiedIdentifier.new(table_name, sk)=>ska), :inherited=>true)
           subclass.instance_eval do
+            dataset.row_proc = rp
             @sti_key = sk
             @sti_key_array = ska
             @sti_dataset = sd
@@ -122,7 +124,7 @@ module Sequel
         # Return an instance of the class specified by sti_key,
         # used by the row_proc.
         def sti_load(r)
-          sti_class(sti_model_map[r[sti_key]]).load(r)
+          sti_class(sti_model_map[r[sti_key]]).call(r)
         end
 
         # Make sure that all subclasses of the parent class correctly include 

data/lib/sequel/plugins/typecast_on_load.rb

@@ -5,7 +5,7 @@ module Sequel
     # typecast correctly (with correct being defined as how the model object
     # would typecast the same column values).
     #
-    # This plugin modifies Model.load to call the setter methods (which typecast
+    # This plugin modifies Model#set_values to call the setter methods (which typecast
     # by default) for all columns given.  You can either specify the columns to
     # typecast on load in the plugin call itself, or afterwards using 
     # add_typecast_on_load_columns:
@@ -41,16 +41,11 @@ module Sequel
           super
           subclass.instance_variable_set(:@typecast_on_load_columns, typecast_on_load_columns.dup)
         end
-
-        # Call the setter method for each of the typecast on load columns,
-        # ensuring the model object will have the correct typecasting even
-        # if the database doesn't typecast the columns correctly.
-        def load(values)
-          super.load_typecast
-        end
       end
 
       module InstanceMethods
+        # Call the setter method for each of the model's typecast_on_load_columns
+        # with the current value, so it can be typecasted correctly.
         def load_typecast
           model.typecast_on_load_columns.each do |c|
             if v = values[c]
@@ -61,10 +56,12 @@ module Sequel
           self
         end
 
-        private
-
-        def _refresh(dataset)
-          super.load_typecast
+        # Typecast values using #load_typecast when the values are retrieved from
+        # the database.
+        def set_values(values)
+          ret = super
+          load_typecast
+          ret
         end
       end
     end

data/lib/sequel/plugins/update_primary_key.rb

@@ -1,6 +1,6 @@
 module Sequel
   module Plugins
-    # The update_primary_key plugin allows you to modify an objects
+    # The update_primary_key plugin allows you to modify an object's
     # primary key and then save the record.  Sequel does not work
     # correctly with primary key modifications by default.  Sequel
     # is designed to work with surrogate primary keys that never need to be
@@ -22,7 +22,7 @@ module Sequel
     module UpdatePrimaryKey
       module ClassMethods
         # Cache the pk_hash when loading records
-        def load(h)
+        def call(h)
           r = super(h)
           r.pk_hash
           r

data/lib/sequel/plugins/xml_serializer.rb

@@ -205,9 +205,9 @@ module Sequel
                 klass.from_xml_node(node)
               end
             elsif cols.include?(k)
-              self[k.to_sym] = node[:nil] ? nil : node.children.first.to_s
+              self[k.to_sym] = node.key?('nil') ? nil : node.children.first.to_s
             elsif meths.include?("#{k}=")
-              send("#{k}=", node[:nil] ? nil : node.children.first.to_s)
+              send("#{k}=", node.key?('nil') ? nil : node.children.first.to_s)
             else
               raise Error, "Entry in XML not an association or column and no setter method exists: #{k}"
             end
@@ -266,7 +266,7 @@ module Sequel
 
           name_proc = model.xml_serialize_name_proc(opts)
           x = model.xml_builder(opts)
-          x.send(name_proc[opts.fetch(:root_name, model.send(:underscore, model.name)).to_s]) do |x1|
+          x.send(name_proc[opts.fetch(:root_name, model.send(:underscore, model.name).gsub('/', '__')).to_s]) do |x1|
             cols.each do |c|
               attrs = {}
               if types