viking-sequel 3.10.0

data/lib/sequel/plugins/composition.rb

@@ -0,0 +1,138 @@
+module Sequel
+  module Plugins
+    # The composition plugin allows you to easily define getter and
+    # setter instance methods for a class where the backing data
+    # is composed of other getters and decomposed to other setters.
+    #
+    # A simple example of this is when you have a database table with
+    # separate columns for year, month, and day, but where you want
+    # to deal with Date objects in your ruby code.  This can be handled
+    # with:
+    #
+    #   Model.composition :date, :mapping=>[:year, :month, :day]
+    #
+    # The :mapping option is optional, but you can define custom
+    # composition and decomposition procs via the :composer and
+    # :decomposer options.
+    #
+    # Note that when using the composition object, you should not
+    # modify the underlying columns if you are also instantiating
+    # the composition, as otherwise the composition object values
+    # will override any underlying columns when the object is saved.
+    module Composition
+      # Define the necessary class instance variables.
+      def self.apply(model)
+        model.instance_eval{@compositions = {}}
+      end
+
+      module ClassMethods
+        # A hash with composition name keys and composition reflection
+        # hash values.
+        attr_reader :compositions
+        
+        # A module included in the class holding the composition
+        # getter and setter methods.
+        attr_reader :composition_module
+        
+        # Define a composition for this model, with name being the name of the composition.
+        # You must provide either a :mapping option or both the :composer and :decomposer options. 
+        #
+        # Options:
+        # * :class - if using the :mapping option, the class to use, as a Class, String or Symbol.
+        # * :composer - A proc that is instance evaled when the composition getter method is called
+        #   to create the composition.
+        # * :decomposer - A proc that is instance evaled before saving the model object,
+        #   if the composition object exists, which sets the columns in the model object
+        #   based on the value of the composition object.
+        # * :mapping - An array where each element is either a symbol or an array of two symbols.
+        #   A symbol is treated like an array of two symbols where both symbols are the same.
+        #   The first symbol represents the getter method in the model, and the second symbol
+        #   represents the getter method in the composition object. Example:
+        #     # Uses columns year, month, and day in the current model
+        #     # Uses year, month, and day methods in the composition object
+        #     :mapping=>[:year, :month, :day]
+        #     # Uses columns year, month, and day in the current model
+        #     # Uses y, m, and d methods in the composition object where
+        #     # for example y in the composition object represents year
+        #     # in the model object.
+        #     :mapping=>[[:year, :y], [:month, :m], [:day, :d]]
+        def composition(name, opts={})
+          opts = opts.dup
+          compositions[name] = opts
+          if mapping = opts[:mapping]
+            keys = mapping.map{|k| k.is_a?(Array) ? k.first : k}
+            if !opts[:composer]              
+              late_binding_class_option(opts, name)
+              klass = opts[:class]
+              class_proc = proc{klass || constantize(opts[:class_name])}
+              opts[:composer] = proc do
+                if values = keys.map{|k| send(k)} and values.any?{|v| !v.nil?}
+                  class_proc.call.new(*values)
+                else
+                  nil
+                end
+              end
+            end
+            if !opts[:decomposer]
+              setter_meths = keys.map{|k| :"#{k}="}
+              cov_methods = mapping.map{|k| k.is_a?(Array) ? k.last : k}
+              setters = setter_meths.zip(cov_methods)
+              opts[:decomposer] = proc do
+                if (o = compositions[name]).nil?
+                  setter_meths.each{|sm| send(sm, nil)}
+                else
+                  setters.each{|sm, cm| send(sm, o.send(cm))}
+                end
+              end
+            end
+          end
+          raise(Error, "Must provide :composer and :decomposer options, or :mapping option") unless opts[:composer] && opts[:decomposer]
+          define_composition_accessor(name, opts)
+        end
+        
+        # Copy the necessary class instance variables to the subclass.
+        def inherited(subclass)
+          super
+          c = compositions.dup
+          subclass.instance_eval{@compositions = c}
+        end
+        
+        # Define getter and setter methods for the composition object.
+        def define_composition_accessor(name, opts={})
+          include(@composition_module ||= Module.new) unless composition_module
+          composer = opts[:composer]
+          composition_module.class_eval do
+            define_method(name) do 
+              compositions.include?(name) ? compositions[name] : (compositions[name] = instance_eval(&composer))
+            end
+            define_method("#{name}=") do |v|
+              modified!
+              compositions[name] = v
+            end
+          end
+        end
+      end
+
+      module InstanceMethods
+        # Clear the cached compositions when refreshing.
+        def _refresh(ds)
+          v = super
+          compositions.clear
+          v
+        end
+
+        # For each composition, set the columns in the model class based
+        # on the composition object.
+        def before_save
+          @compositions.keys.each{|n| instance_eval(&model.compositions[n][:decomposer])} if @compositions
+          super
+        end
+        
+        # Cache of composition objects for this class.
+        def compositions
+          @compositions ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/force_encoding.rb

@@ -0,0 +1,72 @@
+if RUBY_VERSION >= '1.9.0'
+module Sequel
+  module Plugins
+    # The ForceEncoding plugin allows you force specific encodings for all
+    # strings that are used by the model.  When model instances are loaded
+    # from the database, all values in the hash that are strings are
+    # forced to the given encoding.  Whenever you update a model column
+    # 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:
+    #
+    #   class Album < Sequel::Model
+    #     plugin :force_encoding, 'UTF-8'
+    #     # or
+    #     plugin :force_encoding
+    #     self.forced_encoding = 'UTF-8'
+    #   end
+    module ForceEncoding
+      # Set the forced_encoding based on the value given in the plugin call.
+      # Note that if a the plugin has been previously loaded, any previous
+      # forced encoding is overruled, even if no encoding is given when calling
+      # the plugin.
+      def self.configure(model, encoding=nil)
+        model.forced_encoding = encoding
+      end
+      
+      module ClassMethods
+        # The string encoding to force on a column string values
+        attr_accessor :forced_encoding
+        
+        # Copy the forced_encoding value into the subclass
+        def inherited(subclass)
+          super
+          subclass.forced_encoding = forced_encoding
+        end
+      end
+    
+      module InstanceMethods
+        # Allow the force encoding plugin to work with the identity_map
+        # plugin by typecasting new values.
+        def merge_db_update(row)
+          super(force_hash_encoding(row))
+        end
+        
+        private
+        
+        # Force the encoding for all string values in the given row hash.
+        def force_hash_encoding(row)
+          fe = model.forced_encoding
+          row.values.each{|v| v.force_encoding(fe) if v.is_a?(String)} if fe
+          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
+          s.force_encoding(model.forced_encoding) if s.is_a?(String) && model.forced_encoding
+          s
+        end
+      end
+    end
+  end
+end
+else
+  raise LoadError, 'ForceEncoding plugin only works on Ruby 1.9+'
+end

data/lib/sequel/plugins/hook_class_methods.rb

@@ -0,0 +1,126 @@
+module Sequel
+  module Plugins
+    # Sequel's built-in hook class methods plugin is designed for backwards
+    # compatibility.  Its use is not encouraged, it is recommended to use
+    # instance methods and super instead of this plugin.  What this plugin
+    # allows you to do is, for example:
+    #
+    #   # Block only, can cause duplicate hooks if code is reloaded
+    #   before_save{self.created_at = Time.now}
+    #   # Block with tag, safe for reloading
+    #   before_save(:set_created_at){self.created_at = Time.now}
+    #   # Tag only, safe for reloading, calls instance method
+    #   before_save(:set_created_at)
+    #
+    # Pretty much anything you can do with a hook class method, you can also
+    # do with an instance method instead:
+    #
+    #    def before_save
+    #      return false if super == false
+    #      self.created_at = Time.now
+    #    end
+    #
+    # Note that returning false in any before hook block will skip further
+    # before hooks and abort the action.  So if a before_save hook block returns
+    # false, future before_save hook blocks are not called, and the save is aborted.
+    module HookClassMethods
+      # Set up the hooks instance variable in the model.
+      def self.apply(model)
+        hooks = model.instance_variable_set(:@hooks, {})
+        Model::HOOKS.each{|h| hooks[h] = []}
+      end
+
+      module ClassMethods
+        Model::HOOKS.each{|h| class_eval("def #{h}(method = nil, &block); add_hook(:#{h}, method, &block) end", __FILE__, __LINE__)}
+
+        # This adds a new hook type. It will define both a class
+        # method that you can use to add hooks, as well as an instance method
+        # that you can use to call all hooks of that type.  The class method
+        # can be called with a symbol or a block or both.  If a block is given and
+        # and symbol is not, it adds the hook block to the hook type.  If a block
+        # and symbol are both given, it replaces the hook block associated with
+        # that symbol for a given hook type, or adds it if there is no hook block
+        # with that symbol for that hook type.  If no block is given, it assumes
+        # the symbol specifies an instance method to call and adds it to the hook
+        # type.
+        #
+        # If any hook block returns false, the instance method will return false
+        # immediately without running the rest of the hooks of that type.
+        #
+        # It is recommended that you always provide a symbol to this method,
+        # for descriptive purposes.  It's only necessary to do so when you 
+        # are using a system that reloads code.
+        # 
+        # Example of usage:
+        #
+        #  class MyModel
+        #   define_hook :before_move_to
+        #   before_move_to(:check_move_allowed){|o| o.allow_move?}
+        #   def move_to(there)
+        #     return if before_move_to == false
+        #     # move MyModel object to there
+        #   end
+        #  end
+        def add_hook_type(*hooks)
+          Model::HOOKS.concat(hooks)
+          hooks.each do |hook|
+            @hooks[hook] = []
+            instance_eval("def #{hook}(method = nil, &block); add_hook(:#{hook}, method, &block) end", __FILE__, __LINE__)
+            class_eval("def #{hook}; run_hooks(:#{hook}); end", __FILE__, __LINE__)
+          end
+        end
+    
+        # Returns true if there are any hook blocks for the given hook.
+        def has_hooks?(hook)
+          !@hooks[hook].empty?
+        end
+    
+        # Yield every block related to the given hook.
+        def hook_blocks(hook)
+          @hooks[hook].each{|k,v| yield v}
+        end
+
+        # 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}
+        end
+    
+        private
+    
+        # Add a hook block to the list of hook methods.
+        # If a non-nil tag is given and it already is in the list of hooks,
+        # replace it with the new block.
+        def add_hook(hook, tag, &block)
+          unless block
+            (raise Error, 'No hook method specified') unless tag
+            block = proc {send tag}
+          end
+          h = @hooks[hook]
+          if tag && (old = h.find{|x| x[0] == tag})
+            old[1] = block
+          else
+            if hook.to_s =~ /^before/
+              h.unshift([tag,block])
+            else
+              h << [tag, block]
+            end
+          end
+        end
+      end
+
+      module InstanceMethods
+        Model::HOOKS.each{|h| class_eval("def #{h}; return false if super == false; run_hooks(:#{h}); end", __FILE__, __LINE__)}
+
+        private
+
+        # Runs all hook blocks of given hook type on this object.
+        # Stops running hook blocks and returns false if any hook block returns false.
+        def run_hooks(hook)
+          model.hook_blocks(hook){|block| return false if instance_eval(&block) == false}
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/identity_map.rb

@@ -0,0 +1,116 @@
+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
+        # Remove instances from the identity map cache if they are deleted.
+        def delete
+          super
+          if idm = model.identity_map
+            idm.delete(model.identity_map_key(pk))
+          end
+          self
+        end
+
+        # 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[:type] == :many_to_one and opts[:primary_key] == klass.primary_key and
+           opts[:key] and pk = send(opts[:key]) and o = idm[klass.identity_map_key(pk)]
+            o
+          else
+            super
+          end
+        end
+      end
+    end
+  end
+end