sequel 2.11.0 → 2.12.0

data/lib/sequel/model/plugins.rb

@@ -0,0 +1,76 @@
+module Sequel
+  # Empty namespace that plugins should use to store themselves,
+  # 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 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.
+  module Plugins
+  end
+  
+  class Model
+    # Loads a plugin for use with the model class, passing optional arguments
+    # to the plugin.  If the plugin is a module, load it directly.  Otherwise,
+    # 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)
+      arg = args.first
+      block = 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)
+        end
+        dataset_method_modules << m::DatasetMethods
+        def_dataset_method(*m::DatasetMethods.public_instance_methods.reject{|x| NORMAL_METHOD_NAME_REGEXP !~ x.to_s})
+      end
+    end
+    
+    module ClassMethods
+      private
+  
+      # Returns the new style location for the plugin name.
+      def plugin_gem_location(plugin)
+        "sequel/plugins/#{plugin}"
+      end
+
+      # Returns the old style location for the plugin name.
+      def plugin_gem_location_old(plugin)
+        "sequel_#{plugin}"
+      end
+  
+      # Returns the module for the specified plugin. If the module is not 
+      # defined, the corresponding plugin gem is automatically loaded.
+      def plugin_module(plugin)
+        module_name = plugin.to_s.gsub(/(^|_)(.)/){|x| x[-1..-1].upcase}
+        if not Sequel::Plugins.const_defined?(module_name)
+          begin
+            require plugin_gem_location(plugin)
+          rescue LoadError
+            require plugin_gem_location_old(plugin)
+          end
+        end
+        Sequel::Plugins.const_get(module_name)
+      end
+    end
+  end
+end

data/lib/sequel/plugins/caching.rb

@@ -0,0 +1,122 @@
+module Sequel
+  module Plugins
+    # Sequel's built-in caching plugin supports caching to any object that
+    # implements the Ruby-Memcache API.  You can add caching for any model
+    # or for all models via:
+    #
+    #   Model.plugin :caching, store   # Cache all models
+    #   MyModel.plugin :caching, store # Just cache MyModel
+    #
+    # The cache store should implement the Ruby-Memcache API:
+    #
+    #    cache_store.set(key, obj, time) # Associate the obj with the given key
+    #                                    # in the cache for the time (specified
+    #                                    # in seconds)
+    #    cache_store.get(key) => obj # Returns object set with same key
+    #    cache_store.get(key2) => nil # nil returned if there isn't an object
+    #                                 # currently in the cache with that key
+    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={})
+        model.instance_eval do
+          @cache_store = store
+          @cache_ttl = opts[:ttl] || 3600
+        end
+      end
+
+      module ClassMethods
+        # The cache store object for the model, which should implement the
+        # Ruby-Memcache API
+        attr_reader :cache_store
+        
+        # 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)
+          @cache_ttl = ttl
+        end
+        
+        # Copy the cache_store and cache_ttl to the subclass.
+        def inherited(subclass)
+          super
+          store = @cache_store
+          ttl = @cache_ttl
+          subclass.instance_eval do
+            @cache_store = store
+            @cache_ttl = ttl
+          end
+        end
+
+        private
+    
+        # Delete the entry with the matching key from the cache
+        def cache_delete(key)
+          @cache_store.delete(key)
+          nil
+        end
+    
+        # Return a key string for the pk
+        def cache_key(pk)
+          "#{self}:#{Array(pk).join(',')}"
+        end
+      end
+
+      module InstanceMethods
+        # Remove the object from the cache when updating
+        def before_update
+          return false if super == false
+          cache_delete
+        end
+
+        # Return a key unique to the underlying record for caching, based on the
+        # primary key value(s) for the object.  If the model does not have a primary
+        # key, raise an Error.
+        def cache_key
+          raise(Error, "No primary key is associated with this model") unless key = primary_key
+          pk = case key
+          when Array
+            key.collect{|k| @values[k]}
+          else
+            @values[key] || (raise Error, 'no primary key for this record')
+          end
+          model.send(:cache_key, pk)
+        end
+    
+        # Remove the object from the cache when deleting
+        def delete
+          cache_delete
+          super
+        end
+
+        # Remove the object from the cache when updating
+        def update_values(*args)
+          cache_delete
+          super
+        end
+
+        private
+    
+        # Delete this object from the cache
+        def cache_delete
+          model.send(:cache_delete, cache_key)
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/hook_class_methods.rb

@@ -0,0 +1,122 @@
+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
+    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}; 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/schema.rb

@@ -0,0 +1,53 @@
+module Sequel
+  module Plugins
+    module Schema
+      module ClassMethods
+        # Creates table, using the column information from set_schema.
+        def create_table
+          db.create_table(table_name, :generator=>@schema)
+          @db_schema = get_db_schema(true)
+          columns
+        end
+        
+        # Drops the table if it exists and then runs create_table.  Should probably
+        # not be used except in testing.
+        def create_table!
+          drop_table rescue nil
+          create_table
+        end
+        
+        # Drops table.
+        def drop_table
+          db.drop_table(table_name)
+        end
+    
+        # Returns table schema created with set_schema for direct descendant of Model.
+        # Does not retreive schema information from the database, see db_schema if you
+        # want that.
+        def schema
+          @schema || (superclass.schema unless superclass == Model)
+        end
+    
+        # Defines a table schema (see Schema::Generator for more information).
+        #
+        # This is only needed if you want to use the create_table/create_table! methods.
+        # Will also set the dataset if you provide a name, as well as setting
+        # the primary key if you defined one in the passed block.
+        #
+        # In general, it is a better idea to use migrations for production code, as
+        # migrations allow changes to existing schema.  set_schema is mostly useful for
+        # test code or simple examples.
+        def set_schema(name = nil, &block)
+          set_dataset(db[name]) if name
+          @schema = Sequel::Schema::Generator.new(db, &block)
+          set_primary_key(@schema.primary_key_name) if @schema.primary_key_name
+        end
+        
+        # Returns true if table exists, false otherwise.
+        def table_exists?
+          db.table_exists?(table_name)
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/serialization.rb

@@ -0,0 +1,117 @@
+module Sequel
+  module Plugins
+    # Sequel's built in Serialization plugin allows you to keep serialized
+    # ruby objects in the database, while giving you deserialized objects
+    # when you call an accessor.
+    # 
+    # This plugin works by keeping the serialized value in the values, and
+    # adding a @deserialized_values hash.  The reader method for serialized columns
+    # will check the @deserialized_values for the value, return it if present,
+    # or deserialized the entry in @values and return it.  The writer method will
+    # set the @deserialized_values entry.  This plugin adds a before_save hook
+    # that serializes all @deserialized_values to @values.
+    #
+    # You can use either marshal or yaml as the serialization format.
+    # If you use yaml, you should require yaml yourself.
+    #
+    # 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.
+    # Otherwise, it is possible that the default column accessors will take
+    # precedence.
+    module Serialization
+      # Set up the column readers to do deserialization and the column writers
+      # to save the value in deserialized_values.
+      def self.apply(model, format, *columns)
+        raise(Error, "Unsupported serialization format (#{format}), should be :marshal or :yaml") unless [:marshal, :yaml].include?(format)
+        raise(Error, "No columns given.  The serialization plugin requires you specify which columns to serialize") if columns.empty?
+        model.instance_eval do
+          @serialization_format = format
+          @serialized_columns = columns
+          InstanceMethods.module_eval do
+            columns.each do |column|
+              define_method(column) do 
+                if deserialized_values.has_key?(column)
+                  deserialized_values[column]
+                else
+                  deserialized_values[column] = deserialize_value(@values[column])
+                end
+              end
+              define_method("#{column}=") do |v| 
+                changed_columns << column unless changed_columns.include?(column)
+                deserialized_values[column] = v
+              end
+            end
+          end
+        end
+      end
+
+      module ClassMethods
+        # The serialization format to use, should be :marshal or :yaml
+        attr_reader :serialization_format
+
+        # The columns to serialize
+        attr_reader :serialized_columns
+
+        # Copy the serialization format and columns to serialize into the subclass.
+        def inherited(subclass)
+          super
+          sf = serialization_format
+          sc = serialized_columns
+          subclass.instance_eval do
+            @serialization_format = sf
+            @serialized_columns = sc
+          end
+        end
+      end
+
+      module InstanceMethods
+        # Hash of deserialized values, used as a cache.
+        attr_reader :deserialized_values
+
+        # Set @deserialized_values to the empty hash
+        def initialize(*args, &block)
+          @deserialized_values = {}
+          super
+        end
+
+        # Serialize all deserialized values
+        def before_save
+          super
+          deserialized_values.each do |k,v|
+            @values[k] = serialize_value(v)
+          end
+        end
+        
+        # Empty the deserialized values when refreshing.
+        def refresh
+          @deserialized_values = {}
+          super
+        end
+
+        private
+
+        # Deserialize the column from either marshal or yaml format
+        def deserialize_value(v)
+          return v if v.nil?
+          case model.serialization_format 
+          when :marshal
+            Marshal.load(v.unpack('m')[0]) rescue Marshal.load(v)
+          when :yaml
+            YAML.load v if v
+          end
+        end
+
+        # Serialize the column to either marshal or yaml format
+        def serialize_value(v)
+          return v if v.nil?
+          case model.serialization_format 
+          when :marshal
+            [Marshal.dump(v)].pack('m')
+          when :yaml
+            v.to_yaml
+          end
+        end
+      end
+    end
+  end
+end