sequel 1.5.1 → 2.0.0

data/lib/sequel_model/plugins.rb

@@ -1,48 +1,62 @@
 module Sequel
-  module Plugins; end
+  # Empty namespace that plugins should use to store themselves,
+  # so they can be loaded via Model.is.
+  #
+  # 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
-    class << self
-      # Loads a plugin for use with the model class, passing optional arguments
-      # to the plugin.
-      def is(plugin, *args)
-        m = plugin_module(plugin)
-        if m.respond_to?(:apply)
-          m.apply(self, *args)
-        end
-        if m.const_defined?("InstanceMethods")
-          class_def(:"#{plugin}_opts") {args.first}
-          include(m::InstanceMethods)
-        end
-        if m.const_defined?("ClassMethods")
-          meta_def(:"#{plugin}_opts") {args.first}
-          metaclass.send(:include, m::ClassMethods)
-        end
-        if m.const_defined?("DatasetMethods")
-          unless @dataset
-            raise Sequel::Error, "Plugin cannot be applied because the model class has no dataset"
-          end
-          dataset.meta_def(:"#{plugin}_opts") {args.first}
-          dataset.metaclass.send(:include, m::DatasetMethods)
-        end
+    # Loads a plugin for use with the model class, passing optional arguments
+    # to the plugin. If the plugin has a DatasetMethods module and the model
+    # doesn't have a dataset, raise an Error.
+    def self.is(plugin, *args)
+      m = plugin_module(plugin)
+      raise(Error, "Plugin cannot be applied because the model class has no dataset") if m.const_defined?("DatasetMethods") && !@dataset
+      if m.respond_to?(:apply)
+        m.apply(self, *args)
+      end
+      if m.const_defined?("InstanceMethods")
+        class_def(:"#{plugin}_opts") {args.first}
+        include(m::InstanceMethods)
+      end
+      if m.const_defined?("ClassMethods")
+        meta_def(:"#{plugin}_opts") {args.first}
+        extend(m::ClassMethods)
+      end
+      if m.const_defined?("DatasetMethods")
+        dataset.meta_def(:"#{plugin}_opts") {args.first}
+        dataset.metaclass.send(:include, m::DatasetMethods)
+        def_dataset_method(*m::DatasetMethods.instance_methods)
       end
-      alias_method :is_a, :is
-    
-      private
-        # 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(/(^|_)(.)/) {$2.upcase}
-          if not Sequel::Plugins.const_defined?(module_name)
-            require plugin_gem(plugin)
-          end
-          Sequel::Plugins.const_get(module_name)
-        end
+    end
+    metaalias :is_a, :is
   
-        # Returns the gem name for the given plugin.
-        def plugin_gem(plugin)
-          "sequel_#{plugin}"
-        end
+    ### Private Class Methods ###
+
+    # Returns the gem name for the given plugin.
+    def self.plugin_gem(plugin) # :nodoc:
+      "sequel_#{plugin}"
+    end
+
+    # Returns the module for the specified plugin. If the module is not 
+    # defined, the corresponding plugin gem is automatically loaded.
+    def self.plugin_module(plugin) # :nodoc:
+      module_name = plugin.to_s.gsub(/(^|_)(.)/){|x| x[-1..-1].upcase}
+      if not Sequel::Plugins.const_defined?(module_name)
+        require plugin_gem(plugin)
+      end
+      Sequel::Plugins.const_get(module_name)
     end
+
+    metaprivate :plugin_gem, :plugin_module
   end
 end

data/lib/sequel_model/record.rb

@@ -1,13 +1,56 @@
+# This file holds general instance methods for Sequel::Model
+
 module Sequel
   class Model
-    attr_reader :values
+    # The columns that have been updated.  This isn't completely accurate,
+    # see Model#[]=.
     attr_reader :changed_columns
     
-    # Returns value of attribute.
+    # The hash of attribute values.  Keys are symbols with the names of the
+    # underlying database columns.
+    attr_reader :values
+
+    # Whether this model instance should typecast on attribute assignment
+    attr_writer :typecast_on_assignment
+
+    class_attr_reader :columns, :dataset, :db, :primary_key, :str_columns
+    
+    # Creates new instance with values set to passed-in Hash.
+    # If a block is given, yield the instance to the block.
+    # This method runs the after_initialize hook after
+    # it has optionally yielded itself to the block.
+    #
+    # Arguments:
+    # * values - should be a hash with symbol keys, though
+    #   string keys will work if from_db is false.
+    # * from_db - should only be set by Model.load, forget it
+    #   exists.
+    def initialize(values = nil, from_db = false, &block)
+      values ||=  {}
+      @changed_columns = []
+      @typecast_on_assignment = model.typecast_on_assignment
+      @db_schema = model.db_schema
+      if from_db
+        @new = false
+        @values = values
+      else
+        @values = {}
+        @new = true
+        set_with_params(values)
+      end
+      @changed_columns.clear 
+      
+      yield self if block
+      after_initialize
+    end
+    
+    # Returns value of the column's attribute.
     def [](column)
       @values[column]
     end
-    # Sets value of attribute and marks the column as changed.
+
+    # Sets value of the column's attribute and marks the column as changed.
+    # If the column already has the same value, this is a no-op.
     def []=(column, value)
       # If it is new, it doesn't have a value yet, so we should
       # definitely set the new value.
@@ -15,27 +58,10 @@ module Sequel
       # NULL in the database, so assume it has changed.
       if new? || !@values.include?(column) || value != @values[column]
         @changed_columns << column unless @changed_columns.include?(column)
-        @values[column] = value
+        @values[column] = typecast_value(column, value)
       end
     end
 
-    # Enumerates through all attributes.
-    #
-    # === Example:
-    #   Ticket.find(7).each { |k, v| puts "#{k} => #{v}" }
-    def each(&block)
-      @values.each(&block)
-    end
-    # Returns attribute names.
-    def keys
-      @values.keys
-    end
-
-    # Returns value for <tt>:id</tt> attribute.
-    def id
-      @values[:id]
-    end
-
     # Compares model instances by values.
     def ==(obj)
       (obj.class == model) && (obj.values == @values)
@@ -48,201 +74,126 @@ module Sequel
       pk.nil? ? false : (obj.class == model) && (obj.pk == pk)
     end
 
-    # Unique for objects with the same class and pk (if pk is not nil), or
-    # the same class and values (if pk is nil).
-    def hash
-      [model, pk.nil? ? @values.sort_by{|k,v| k.to_s} : pk].hash
-    end
+    # class is defined in Object, but it is also a keyword,
+    # and since a lot of instance methods call class methods,
+    # the model makes it so you can use model instead of
+    # self.class.
+    alias_method :model, :class
 
-    # Returns key for primary key.
-    def self.primary_key
-      :id
-    end
-    
-    # Returns primary key attribute hash.
-    def self.primary_key_hash(value)
-      {:id => value}
+    # Deletes and returns self.  Does not run destroy hooks.
+    # Look into using destroy instead.
+    def delete
+      before_delete
+      this.delete
+      self
     end
     
-    # Sets primary key, regular and composite are possible.
-    #
-    # == Example:
-    #   class Tagging < Sequel::Model
-    #     # composite key
-    #     set_primary_key :taggable_id, :tag_id
-    #   end
-    #
-    #   class Person < Sequel::Model
-    #     # regular key
-    #     set_primary_key :person_id
-    #   end
-    #
-    # <i>You can even set it to nil!</i>
-    def self.set_primary_key(*key)
-      # if k is nil, we go to no_primary_key
-      if key.empty? || (key.size == 1 && key.first == nil)
-        return no_primary_key
-      end
-      
-      # backwards compat
-      key = (key.length == 1) ? key[0] : key.flatten
-
-      # redefine primary_key
-      meta_def(:primary_key) {key}
-      
-      unless key.is_a? Array # regular primary key
-        class_def(:this) do
-          @this ||= dataset.filter(key => @values[key]).limit(1).naked
-        end
-        class_def(:pk) do
-          @pk ||= @values[key]
-        end
-        class_def(:pk_hash) do
-          @pk ||= {key => @values[key]}
-        end
-        class_def(:cache_key) do
-          pk = @values[key] || (raise Error, 'no primary key for this record')
-          @cache_key ||= "#{self.class}:#{pk}"
-        end
-        meta_def(:primary_key_hash) do |v|
-          {key => v}
-        end
-      else # composite key
-        exp_list = key.map {|k| "#{k.inspect} => @values[#{k.inspect}]"}
-        block = eval("proc {@this ||= self.class.dataset.filter(#{exp_list.join(',')}).limit(1).naked}")
-        class_def(:this, &block)
-        
-        exp_list = key.map {|k| "@values[#{k.inspect}]"}
-        block = eval("proc {@pk ||= [#{exp_list.join(',')}]}")
-        class_def(:pk, &block)
-        
-        exp_list = key.map {|k| "#{k.inspect} => @values[#{k.inspect}]"}
-        block = eval("proc {@this ||= {#{exp_list.join(',')}}}")
-        class_def(:pk_hash, &block)
-        
-        exp_list = key.map {|k| '#{@values[%s]}' % k.inspect}.join(',')
-        block = eval('proc {@cache_key ||= "#{self.class}:%s"}' % exp_list)
-        class_def(:cache_key, &block)
-
-        meta_def(:primary_key_hash) do |v|
-          key.inject({}) {|m, i| m[i] = v.shift; m}
-        end
+    # Like delete but runs hooks before and after delete.
+    # If before_destroy returns false, returns false without
+    # deleting the object the the database. Otherwise, deletes
+    # the item from the database and returns self.
+    def destroy
+      db.transaction do
+        return false if before_destroy == false
+        delete
+        after_destroy
       end
+      self
     end
     
-    def self.no_primary_key #:nodoc:
-      meta_def(:primary_key) {nil}
-      meta_def(:primary_key_hash) {|v| raise Error, "#{self} does not have a primary key"}
-      class_def(:this)      {raise Error, "No primary key is associated with this model"}
-      class_def(:pk)        {raise Error, "No primary key is associated with this model"}
-      class_def(:pk_hash)   {raise Error, "No primary key is associated with this model"}
-      class_def(:cache_key) {raise Error, "No primary key is associated with this model"}
+    # Enumerates through all attributes.
+    #
+    # Example:
+    #   Ticket.find(7).each { |k, v| puts "#{k} => #{v}" }
+    def each(&block)
+      @values.each(&block)
     end
-    
-    # Creates new instance with values set to passed-in Hash, saves it
-    # (running any callbacks), and returns the instance.
-    def self.create(values = {}, &block)
-      obj = new(values, &block)
-      obj.save
-      obj
+
+    # Returns true when current instance exists, false otherwise.
+    def exists?
+      this.count > 0
     end
     
-    # Updates the instance with the supplied values with support for virtual
-    # attributes, ignoring any values for which no setter method is available.
-    # Does not save the record.
-    #
-    # If no columns have been set for this model (very unlikely), assume symbol
-    # keys are valid column names, and assign the column value based on that.
-    def set_with_params(hash)
-      columns_not_set = !model.instance_variable_get(:@columns)
-      meths = setter_methods
-      hash.each do |k,v|
-        m = "#{k}="
-        if meths.include?(m)
-          send(m, v)
-        elsif columns_not_set && (Symbol === k)
-          self[k] = v
-        end
-      end
+    # Unique for objects with the same class and pk (if pk is not nil), or
+    # the same class and values (if pk is nil).
+    def hash
+      [model, pk.nil? ? @values.sort_by{|k,v| k.to_s} : pk].hash
     end
 
-    # Runs set_with_params and saves the changes (which runs any callback methods).
-    def update_with_params(values)
-      set_with_params(values)
-      save_changes
+    # Returns value for the :id attribute, even if the primary key is
+    # not id. To get the primary key value, use #pk.
+    def id
+      @values[:id]
     end
 
-    # Returns (naked) dataset bound to current instance.
-    def this
-      @this ||= self.class.dataset.filter(:id => @values[:id]).limit(1).naked
+    # Returns a string representation of the model instance including
+    # the class name and values.
+    def inspect
+      "#<#{model.name} @values=#{@values.inspect}>"
     end
-    
-    # Returns a key unique to the underlying record for caching
-    def cache_key
-      pk = @values[:id] || (raise Error, 'no primary key for this record')
-      @cache_key ||= "#{self.class}:#{pk}"
+
+    # Returns attribute names as an array of symbols.
+    def keys
+      @values.keys
     end
 
-    # Returns primary key column(s) for object's Model class.
-    def primary_key
-      @primary_key ||= self.class.primary_key
+    # Returns true if the current instance represents a new record.
+    def new?
+      @new
     end
     
-    # Returns the primary key value identifying the model instance. If the
-    # model's primary key is changed (using #set_primary_key or #no_primary_key)
-    # this method is redefined accordingly.
+    # Returns the primary key value identifying the model instance.
+    # Raises an error if this model does not have a primary key.
+    # If the model has a composite primary key, returns an array of values.
     def pk
-      @pk ||= @values[:id]
-    end
-    
-    # Returns a hash identifying the model instance. Stock implementation.
-    def pk_hash
-      @pk_hash ||= {:id => @values[:id]}
-    end
-    
-    # Creates new instance with values set to passed-in Hash.
-    #
-    # This method guesses whether the record exists when
-    # <tt>new_record</tt> is set to false.
-    def initialize(values = nil, from_db = false, &block)
-      values ||=  {}
-      @changed_columns = []
-      if from_db
-        @new = false
-        @values = values
+      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 = {}
-        @new = true
-        set_with_params(values)
+        @values[key]
       end
-      @changed_columns.clear 
-      
-      yield self if block
-      after_initialize
     end
     
-    # Initializes a model instance as an existing record. This constructor is 
-    # used by Sequel to initialize model instances when fetching records.
-    def self.load(values)
-      new(values, true)
-    end
-    
-    # Returns true if the current instance represents a new record.
-    def new?
-      @new
+    # Returns a hash identifying the model instance.  It should be true that:
+    # 
+    #  Model[model_instance.pk_hash] === model_instance
+    def pk_hash
+      model.primary_key_hash(pk)
     end
     
-    # Returns true when current instance exists, false otherwise.
-    def exists?
-      this.count > 0
+    # Reloads attributes from database and returns self. Also clears all
+    # cached association information.  Raises an Error if the record no longer
+    # exists in the database.
+    def refresh
+      @values = this.first || raise(Error, "Record not found")
+      model.all_association_reflections.each do |r|
+        instance_variable_set("@#{r[:name]}", nil)
+      end
+      self
     end
-    
-    # Creates or updates the associated record. This method can also
-    # accept a list of specific columns to update.
+    alias_method :reload, :refresh
+
+    # Creates or updates the record, after making sure the record
+    # is valid.  If the record is not valid, returns false.
+    # If before_save, before_create (if new?), or before_update
+    # (if !new?) return false, returns false.  Otherwise,
+    # returns self.
     def save(*columns)
-      before_save
+      return false unless valid?
+      save!(*columns)
+    end
+
+    # Creates or updates the record, without attempting to validate
+    # it first. You can provide an optional list of columns to update,
+    # in which case it only updates those columns.
+    # If before_save, before_create (if new?), or before_update
+    # (if !new?) return false, returns false.  Otherwise,
+    # returns self.
+    def save!(*columns)
+      return false if before_save == false
       if @new
-        before_create
+        return false if before_create == false
         iid = model.dataset.insert(@values)
         # if we have a regular primary key and it's not set in @values,
         # we assume it's the last inserted id
@@ -256,7 +207,7 @@ module Sequel
         @new = false
         after_create
       else
-        before_update
+        return false if before_update == false
         if columns.empty?
           this.update(@values)
           @changed_columns = []
@@ -291,10 +242,10 @@ module Sequel
         when String
           # Prevent denial of service via memory exhaustion by only 
           # calling to_sym if the symbol already exists.
-          raise(::Sequel::Error, "all string keys must be a valid columns") unless s.include?(k)
+          raise(Error, "all string keys must be a valid columns") unless s.include?(k)
           k.to_sym
         else
-          raise(::Sequel::Error, "Only symbols and strings allows as keys")
+          raise(Error, "Only symbols and strings allows as keys")
         end
         m[k] = v
         m
@@ -303,46 +254,60 @@ module Sequel
       vals
     end
 
+    # Updates the instance with the supplied values with support for virtual
+    # attributes, ignoring any values for which no setter method is available.
+    # Does not save the record.
+    #
+    # If no columns have been set for this model (very unlikely), assume symbol
+    # keys are valid column names, and assign the column value based on that.
+    def set_with_params(hash)
+      columns_not_set = model.instance_variable_get(:@columns).blank?
+      meths = setter_methods
+      hash.each do |k,v|
+        m = "#{k}="
+        if meths.include?(m)
+          send(m, v)
+        elsif columns_not_set && (Symbol === k)
+          self[k] = v
+        end
+      end
+    end
+
+    # Returns (naked) dataset that should return only this instance.
+    def this
+      @this ||= dataset.filter(pk_hash).limit(1).naked
+    end
+    
     # Sets the values attributes with set_values and then updates
     # the record in the database using those values.  This is a
     # low level method that does not run the usual save callbacks.
     # It should probably be avoided.  Look into using update_with_params instead.
     def update_values(values)
+      before_update_values
       this.update(set_values(values))
     end
     
-    # Reloads values from database and returns self.
-    def refresh
-      @values = this.first || raise(Error, "Record not found")
-      model.all_association_reflections.each do |r|
-        instance_variable_set("@#{r[:name]}", nil)
-      end
-      self
+    # Runs set_with_params and runs save_changes (which runs any callback methods).
+    def update_with_params(values)
+      set_with_params(values)
+      save_changes
     end
-    alias_method :reload, :refresh
 
-    # Like delete but runs hooks before and after delete.
-    def destroy
-      db.transaction do
-        before_destroy
-        delete
-        after_destroy
-      end
-      self
+    private
+
+    # Returns all methods that can be used for attribute
+    # assignment (those that end with =)
+    def setter_methods
+      methods.grep(/=\z/)
     end
-    
-    # Deletes and returns self.  Does not run callbacks.
-    # Look into using destroy instead.
-    def delete
-      this.delete
-      self
+
+    # Typecast the value to the column's type if typecasting.  Calls the database's
+    # typecast_value method, so database adapters can override/augment the handling
+    # for database specific column types.
+    def typecast_value(column, value)
+      return value unless @typecast_on_assignment && @db_schema && (col_schema = @db_schema[column])
+      raise(Error, "nil/NULL is not allowed for the #{column} column") if value.nil? && (col_schema[:allow_null] == false)
+      model.db.typecast_value(col_schema[:type], value)
     end
-    
-    private
-      # Returns all methods that can be used for attribute
-      # assignment (those that end with =)
-      def setter_methods
-        methods.grep(/=\z/)
-      end
   end
 end