sequel 2.0.1 → 2.1.0

data/CHANGELOG

@@ -1,3 +1,41 @@
+=== HEAD
+
+* Break association add_/remove_/remove_all_ methods into two parts, for easier overriding (jeremyevans)
+
+* Add Model.strict_param_setting, on by default, which raises errors if a missing/restricted method is called via new/set/update/etc. (jeremyevans)
+
+* Raise errors when using association methods on objects without valid primary keys (jeremyevans)
+
+* The model's primary key is a restricted column by default, Add model.unrestrict_primary_key to get the old behavior (jeremyevans)
+
+* Add Model.set_(allowed|restricted)_columns, which affect which columns create/new/set/update/etc. modify (jeremyevans)
+
+* Calls to Model.def_dataset_method with a block are cached and reapplied to the new dataset if set_dataset is called, even in a subclass (jeremyevans)
+
+* The :reciprocal option to associations should now be the symbol name of the reciprocal association, not an instance variable symbol (jeremyevans)
+
+* Add Model#associations, which is a hash holding a cache of associated objects, with each association being a separate key (jeremyevans)
+
+* Make all associations support a :graph_select option, specifying a column or array of columns to select when using eager_graph (jeremyevans)
+
+* Bring back Model#set and Model#update, now the same as Model#set_with_params and Model#update_with_params (jeremyevans)
+
+* Allow model datasets to call to_hash without any arguments, which allows easy creation of identity maps (jeremyevans)
+
+* Add Model.set_sti_key, for easily setting up single table inheritance (jeremyevans)
+
+* Make all associations support a :read_only option, which doesn't add methods that modify the database (jeremyevans)
+
+* Make *_to_many associations support a :limit option, for specifying a limit to the resulting records (and possibly an offset) (jeremyevans)
+
+* Make association block argument and :eager option affect the _dataset method (jeremyevans)
+
+* Add a :one_to_one option to one_to_many associations, which creates a getter and setter similar to many_to_one (a.k.a. has_one) (jeremyevans)
+
+* add_ and remove_ one_to_many association methods now raise an error if the passed object cannot be saved, instead of saving without validation (jeremyevans)
+
+* Add support for :if option on validations, using a symbol (specifying an instance method) or a proc (dtsato)
+
 === 2.0.1 (2008-06-04)
 
 * Make the choice of Time or DateTime optional for typecasting :datetime types, default to Time (jeremyevans)

data/README

@@ -26,8 +26,7 @@ You can, however, explicitly set the table name or even the dataset used:
 * {Source code}[http://github.com/jeremyevans/sequel]
 * {Bug tracking}[http://code.google.com/p/ruby-sequel/issues/list]
 * {Google group}[http://groups.google.com/group/sequel-talk]
-* {RubyForge page}[http://rubyforge.org/projects/sequel/]
-* {API RDoc}[http://sequel.rubyforge.org]
+* {RDoc}[http://sequel.rubyforge.org]
 
 To check out the source code:
 
@@ -127,11 +126,11 @@ Hooks are defined by supplying a block:
 
   class Post < Sequel::Model
     after_create do
-      self.created_at = Time.now
+      author.increase_post_count
     end
 
     after_destroy do
-      author.update_post_count
+      author.decrease_post_count
     end
   end
 

data/Rakefile

@@ -9,8 +9,8 @@ include FileUtils
 # Configuration
 ##############################################################################
 NAME = "sequel"
-VERS = "2.0.1"
-SEQUEL_CORE_VERS= "2.0.1"
+VERS = "2.1.0"
+SEQUEL_CORE_VERS= "2.1.0"
 CLEAN.include ["**/.*.sw?", "pkg", ".config", "rdoc", "coverage"]
 RDOC_OPTS = ["--quiet", "--line-numbers", "--inline-source", '--title', \
   'Sequel: The Database Toolkit for Ruby: Model Classes', '--main', 'README']
@@ -60,13 +60,13 @@ end
 desc "Install sequel gem"
 task :install do
   sh %{rake package}
-  sh %{sudo gem install pkg/#{NAME}-#{VERS}}
+  sh %{sudo gem install pkg/#{NAME}-#{VERS} --local}
 end
 
 desc "Install sequel gem without docs"
 task :install_no_docs do
   sh %{rake package}
-  sh %{sudo gem install pkg/#{NAME}-#{VERS} --no-rdoc --no-ri}
+  sh %{sudo gem install pkg/#{NAME}-#{VERS} --no-rdoc --no-ri --local}
 end
 
 desc "Uninstall sequel gem"

data/lib/sequel_model.rb

@@ -1,5 +1,5 @@
 require 'sequel_core'
-%w"inflector base hooks record schema association_reflection 
+%w"inflector base hooks record schema association_reflection dataset_methods 
   associations caching plugins validations eager_loading".each do |f|
   require "sequel_model/#{f}"
 end
@@ -49,9 +49,29 @@ module Sequel
   #   should not override these instance methods.
   # * The following instance_methods all call the class method of the same
   #   name: columns, dataset, db, primary_key, str_columns.
+  # * The following class level attr_readers are created: allowed_columns,
+  #   cache_store, cache_ttl, dataset_methods, primary_key, restricted_columns,
+  #   sti_dataset, and sti_key.  You should not usually need to
+  #   access these directly.
+  # * The following class level attr_accessors are created: strict_param_setting
+  #   and typecast_on_assignment:
+  #
+  #     # Don't raise errors in new/set/update/etc. if an attempt to
+  #     # access a missing/restricted method occurs (just silently
+  #     # skip it)
+  #     Model.strict_param_setting = false
+  #     Model.new(:id=>1) # No Error
+  #     # Don't typecast attribute values on assignment
+  #     Model.typecast_on_assignment = false
+  #     m = Model.new
+  #     m.number = '10'
+  #     m.number # => '10' instead of 10
+  #
+  # * The following class level method aliases are defined:
+  #   * Model.dataset= => set_dataset
+  #   * Model.is_a => is
   class Model
     extend Enumerable
     extend Associations
-    include Validation
   end
 end

data/lib/sequel_model/association_reflection.rb

@@ -28,14 +28,14 @@ module Sequel
             associated_class.all_association_reflections.each do |assoc_reflect|
               if assoc_reflect[:type] == :many_to_many && assoc_reflect[:left_key] == right_key \
                  && assoc_reflect[:right_key] == left_key && assoc_reflect[:join_table] == join_table
-                return self[:reciprocal] = association_ivar(assoc_reflect[:name])
+                return self[:reciprocal] = assoc_reflect[:name]
               end
             end
           else
             key = self[:key]
             associated_class.all_association_reflections.each do |assoc_reflect|
               if assoc_reflect[:type] == reciprocal_type && assoc_reflect[:key] == key
-                return self[:reciprocal] = association_ivar(assoc_reflect[:name])
+                return self[:reciprocal] = assoc_reflect[:name]
               end
             end
           end
@@ -46,13 +46,6 @@ module Sequel
         def select
          self[:select] ||= associated_class.table_name.*
         end
-  
-        private
-
-        # Name symbol of association instance variable
-        def association_ivar(name)
-          :"@#{name}"
-        end
       end
     end
   end

data/lib/sequel_model/associations.rb

@@ -21,6 +21,12 @@
 # * remove_milestone(obj) - Removes the association with the passed milestone
 # * remove_all_milestones - Removes associations with all associated milestones
 #
+# If you want to override the behavior of the add_/remove_/remove_all_ methods,
+# there are private instance methods created that a prepended with an
+# underscore (e.g. _add_milestone).  The private instance methods can be
+# easily overridden, but you shouldn't override the public instance methods,
+# as they deal with how associations are cached.
+#
 # By default the classes for the associations are inferred from the association
 # name, so for example the Project#portfolio will return an instance of 
 # Portfolio, and Project#milestones will return an array of Milestone 
@@ -68,6 +74,12 @@ module Sequel::Model::Associations
   #   model object can be associated with many current model objects.
   #   Similar to ActiveRecord/DataMapper's has_and_belongs_to_many.
   #
+  # A one to one relationship can be set up with a many_to_one association
+  # on the table with the foreign key, and a one_to_many association with the
+  # :one_to_one option specified on the table without the foreign key.  The
+  # two associations will operate similarly, except that the many_to_one
+  # association setter doesn't update the database until you call save manually.
+  # 
   # The following options can be supplied:
   # * *ALL types*:
   #   - :allow_eager - If set to false, you cannot load the association eagerly
@@ -86,9 +98,14 @@ module Sequel::Model::Associations
   #     the association via eager_graph
   #   - :graph_join_type - The type of SQL join to use when eagerly loading the association via
   #     eager_graph
+  #   - :graph_select - A column or array of columns to select from the associated table
+  #     when eagerly loading the association via eager_graph. Defaults to all
+  #     columns in the associated table.
   #   - :order - the column(s) by which to order the association dataset.  Can be a
   #     singular column or an array.
-  #   - :reciprocal - the symbol name of the instance variable of the reciprocal association,
+  #   - :read_only - Do not add a setter method (for many_to_one or one_to_many with :one_to_one),
+  #     or add_/remove_/remove_all_ methods (for one_to_many, many_to_many)
+  #   - :reciprocal - the symbol name of the reciprocal association,
   #     if it exists.  By default, sequel will try to determine it by looking at the
   #     associated model's assocations for a association that matches
   #     the current association's key(s).  Set to nil to not use a reciprocal.
@@ -98,6 +115,9 @@ module Sequel::Model::Associations
   #     use this option, but beware that the join table attributes can clash with
   #     attributes from the model table, so you should alias any attributes that have
   #     the same name in both the join table and the associated table.
+  # * :one_to_many, :many_to_many:
+  #   - :limit - Limit the number of records to the provided value.  Use
+  #     an array with two arguments for the value to specify a limit and offset.
   # * :many_to_one:
   #   - :key - foreign_key in current model's table that references
   #     associated model's primary key, as a symbol.  Defaults to :"#{name}_id".
@@ -105,6 +125,14 @@ module Sequel::Model::Associations
   #   - :key - foreign key in associated model's table that references
   #     current model's primary key, as a symbol.  Defaults to
   #     :"#{self.name.underscore}_id".
+  #   - :one_to_one: Create a getter and setter similar to those of many_to_one
+  #     associations.  The getter returns a singular matching record, or raises an
+  #     error if multiple records match.  The setter updates the record given and removes
+  #     associations with all other records. When this option is used, the other
+  #     association methods usually added are either removed or made private,
+  #     so using this is similar to using many_to_one, in terms of the methods
+  #     it adds, the main difference is that the foreign key is in the associated
+  #     table instead of the current table.
   # * :many_to_many:
   #   - :join_table - name of table that includes the foreign keys to both
   #     the current model and the associated model, as a symbol.  Defaults to the name
@@ -126,6 +154,7 @@ module Sequel::Model::Associations
     opts[:eager_block] = block unless opts.include?(:eager_block)
     opts[:graph_join_type] ||= :left_outer
     opts[:graph_conditions] = opts[:graph_conditions] ? opts[:graph_conditions].to_a : []
+    opts[:graph_select] = Array(opts[:graph_select]) if opts[:graph_select]
 
     # find class
     case opts[:class]
@@ -177,11 +206,6 @@ module Sequel::Model::Associations
     :"add_#{name.to_s.singularize}"
   end
 
-  # Name symbol of association instance variable
-  def association_ivar(name)
-    :"@#{name}"
-  end
-  
   # Name symbol for remove_all association method
   def association_remove_all_method_name(name)
     :"remove_all_#{name}"
@@ -203,47 +227,44 @@ module Sequel::Model::Associations
     dataset_method = :"#{name}_dataset"
     helper_method = :"#{name}_helper"
     dataset_block = opts[:block]
-    ivar = association_ivar(name)
-    
-    # define a method returning the association dataset (with optional order)
-    if order = opts[:order]
-      class_def(dataset_method) {instance_eval(&block).order(*order)}
-    else
-      class_def(dataset_method, &block)
-    end
-    
+    order = opts[:order]
+    eager = opts[:eager]
+    limit = opts[:limit]
+
     # If a block is given, define a helper method for it, because it takes
     # an argument.  This is unnecessary in Ruby 1.9, as that has instance_exec.
     if dataset_block
       class_def(helper_method, &dataset_block)
+      private helper_method
+    end
+    
+    # define a method returning the association dataset (with optional order)
+    class_def(dataset_method) do
+      raise(Sequel::Error, 'model object does not have a primary key') unless pk
+      ds = instance_eval(&block).select(*opts.select)
+      ds = ds.order(*order) if order
+      ds = ds.limit(*limit) if limit
+      ds = ds.eager(eager) if eager
+      ds = send(helper_method, ds) if dataset_block
+      ds
     end
     
     class_def(name) do |*reload|
-      if !reload[0] && obj = instance_variable_get(ivar)
-        obj
+      if (assoc = @associations).include?(name) and !reload[0]
+        assoc[name]
       else
-        ds = send(dataset_method)
-        # if the a dataset block was specified, we need to call it and use
-        # the result as the dataset to fetch records from.
-        if dataset_block
-          ds = send(helper_method, ds)
-        end
-        if eager = opts[:eager]
-          ds = ds.eager(eager)
-        end
-        objs = ds.all
+        objs = send(dataset_method).all
         # Only one_to_many associations should set the reciprocal object
         if (opts[:type] == :one_to_many) && (reciprocal = opts.reciprocal)
-          objs.each{|o| o.instance_variable_set(reciprocal, self)}
+          objs.each{|o| o.associations[reciprocal] = self}
         end
-        instance_variable_set(ivar, objs)
+        assoc[name] = objs
       end
     end
   end
 
   # Adds many_to_many association instance methods
   def def_many_to_many(name, opts)
-    ivar = association_ivar(name)
     left = (opts[:left_key] ||= default_remote_key)
     right = (opts[:right_key] ||= default_foreign_key(opts))
     opts[:class_name] ||= name.to_s.singularize.camelize
@@ -254,75 +275,100 @@ module Sequel::Model::Associations
     database = db
     
     def_association_dataset_methods(name, opts) do
-      opts.associated_class.select(*opts.select).inner_join(join_table, [[right, opts.associated_primary_key], [left, pk]])
+      opts.associated_class.inner_join(join_table, [[right, opts.associated_primary_key], [left, pk]])
     end
 
-    class_def(association_add_method_name(name)) do |o|
+    return if opts[:read_only]
+
+    add_meth = association_add_method_name(name)
+    internal_add_meth = :"_#{add_meth}"
+    remove_meth = association_remove_method_name(name)
+    internal_remove_meth = :"_#{remove_meth}"
+    remove_all_meth = association_remove_all_method_name(name)
+    internal_remove_all_meth = :"_#{remove_all_meth}"
+
+    class_def(internal_add_meth) do |o|
       database[join_table].insert(left=>pk, right=>o.pk)
-      if arr = instance_variable_get(ivar)
-        arr.push(o)
+    end
+    class_def(internal_remove_meth) do |o|
+      database[join_table].filter([[left, pk], [right, o.pk]]).delete
+    end
+    class_def(internal_remove_all_meth) do
+      database[join_table].filter(left=>pk).delete
+    end
+    private internal_add_meth, internal_remove_meth, internal_remove_all_meth
+
+    class_def(add_meth) do |o|
+      raise(Sequel::Error, 'model object does not have a primary key') unless pk && o.pk
+      send(internal_add_meth, o)
+      if (assoc = @associations).include?(name)
+        assoc[name].push(o)
       end
-      if (reciprocal = opts.reciprocal) && (list = o.instance_variable_get(reciprocal)) \
-         && !(list.include?(self))
-        list.push(self)
+      if reciprocal = opts.reciprocal and array = o.associations[reciprocal] and !array.include?(self)
+        array.push(self)
       end
       o
     end
-    class_def(association_remove_method_name(name)) do |o|
-      database[join_table].filter([[left, pk], [right, o.pk]]).delete
-      if arr = instance_variable_get(ivar)
-        arr.delete(o)
+    class_def(remove_meth) do |o|
+      raise(Sequel::Error, 'model object does not have a primary key') unless pk && o.pk
+      send(internal_remove_meth, o)
+      if (assoc = @associations).include?(name)
+        assoc[name].delete_if{|x| o === x}
       end
-      if (reciprocal = opts.reciprocal) && (list = o.instance_variable_get(reciprocal))
-        list.delete(self)
+      if reciprocal = opts.reciprocal and array = o.associations[reciprocal]
+        array.delete_if{|x| self === x}
       end
       o
     end
-    class_def(association_remove_all_method_name(name)) do
-      database[join_table].filter(left=>pk).delete
-      if arr = instance_variable_get(ivar)
+    class_def(remove_all_meth) do
+      raise(Sequel::Error, 'model object does not have a primary key') unless pk
+      send(internal_remove_all_meth)
+      if (assoc = @associations).include?(name)
         reciprocal = opts.reciprocal
+        arr = assoc[name]
         ret = arr.dup
         arr.each do |o|
-          if reciprocal && (list = o.instance_variable_get(reciprocal))
-            list.delete(self)
+          if reciprocal and array = o.associations[reciprocal]
+            array.delete_if{|x| self === x}
           end
         end
       end
-      instance_variable_set(ivar, [])
+      assoc[name] = []
       ret
     end
   end
   
   # Adds many_to_one association instance methods
   def def_many_to_one(name, opts)
-    ivar = association_ivar(name)
-    
     key = (opts[:key] ||= default_foreign_key(opts))
     opts[:class_name] ||= name.to_s.camelize
     
     class_def(name) do |*reload|
-      if !reload[0] && obj = instance_variable_get(ivar)
-        obj == :null ? nil : obj
+      if (assoc = @associations).include?(name) and !reload[0]
+        assoc[name]
       else
         obj = if fk = send(key)
           opts.associated_class.select(*opts.select).filter(opts.associated_primary_key=>fk).first
         end
-        instance_variable_set(ivar, obj || :null)
-        obj
+        assoc[name] = obj
       end
     end
+    return if opts[:read_only]
 
-    class_def(:"#{name}=") do |o|
-      old_val = instance_variable_get(ivar) if reciprocal = opts.reciprocal
-      instance_variable_set(ivar, o)
+    class_def(:"#{name}=") do |o|  
+      raise(Sequel::Error, 'model object does not have a primary key') if o && !o.pk
+      reciprocal = opts.reciprocal
+      if (assoc = @associations).include?(name) and reciprocal
+        old_val = assoc[name]
+      end
+      assoc[name] = o
       send(:"#{key}=", (o.pk if o))
-      if reciprocal && (old_val != o)
-        if old_val && (list = old_val.instance_variable_get(reciprocal))
-          list.delete(self)
+      if reciprocal and old_val != o
+        if old_val and array = old_val.associations[reciprocal]
+          array.delete_if{|x| self === x}
         end
-        if o && (list = o.instance_variable_get(reciprocal)) && !(list.include?(self))
-          list.push(self) 
+        if o and array = o.associations[reciprocal] and !array.include?(self)
+          array.push(self) 
         end
       end
       o
@@ -331,44 +377,91 @@ module Sequel::Model::Associations
   
   # Adds one_to_many association instance methods
   def def_one_to_many(name, opts)
-    ivar = association_ivar(name)
     key = (opts[:key] ||= default_remote_key)
     opts[:class_name] ||= name.to_s.singularize.camelize
     
-    def_association_dataset_methods(name, opts) {opts.associated_class.select(*opts.select).filter(key => pk)}
+    def_association_dataset_methods(name, opts) {opts.associated_class.filter(key => pk)}
     
-    class_def(association_add_method_name(name)) do |o|
-      o.send(:"#{key}=", pk)
-      o.save!
-      if arr = instance_variable_get(ivar)
-        arr.push(o)
-      end
-      if reciprocal = opts.reciprocal
-        o.instance_variable_set(reciprocal, self)
+    unless opts[:read_only]
+      add_meth = association_add_method_name(name)
+      internal_add_meth = :"_#{add_meth}"
+      class_def(internal_add_meth) do |o|
+        o.send(:"#{key}=", pk)
+        o.save || raise(Sequel::Error, "invalid associated object, cannot save")
       end
-      o
-    end
-    class_def(association_remove_method_name(name)) do |o|
-      o.send(:"#{key}=", nil)
-      o.save!
-      if arr = instance_variable_get(ivar)
-        arr.delete(o)
+      private internal_add_meth
+
+      class_def(add_meth) do |o|
+        raise(Sequel::Error, 'model object does not have a primary key') unless pk
+        send(internal_add_meth, o)
+        if (assoc = @associations).include?(name)
+          assoc[name].push(o)
+        end
+        if reciprocal = opts.reciprocal
+          o.associations[reciprocal] = self
+        end
+        o
       end
-      if reciprocal = opts.reciprocal
-        o.instance_variable_set(reciprocal, :null)
+      unless opts[:one_to_one]
+        remove_meth = association_remove_method_name(name)
+        internal_remove_meth = :"_#{remove_meth}"
+        remove_all_meth = association_remove_all_method_name(name)
+        internal_remove_all_meth = :"_#{remove_all_meth}"
+
+        class_def(internal_remove_meth) do |o|
+          o.send(:"#{key}=", nil)
+          o.save || raise(Sequel::Error, "invalid associated object, cannot save")
+        end
+        class_def(internal_remove_all_meth) do
+          opts.associated_class.filter(key=>pk).update(key=>nil)
+        end
+        private internal_remove_meth, internal_remove_all_meth
+
+        class_def(remove_meth) do |o|
+          raise(Sequel::Error, 'model object does not have a primary key') unless pk
+          send(internal_remove_meth, o)
+          if (assoc = @associations).include?(name)
+            assoc[name].delete_if{|x| o === x}
+          end
+          if reciprocal = opts.reciprocal
+            o.associations[reciprocal] = nil
+          end
+          o
+        end
+        class_def(remove_all_meth) do
+          raise(Sequel::Error, 'model object does not have a primary key') unless pk
+          send(internal_remove_all_meth)
+          if (assoc = @associations).include?(name)
+            arr = assoc[name]
+            ret = arr.dup
+            if reciprocal = opts.reciprocal
+              arr.each{|o| o.associations[reciprocal] = nil}
+            end
+          end
+          assoc[name] = []
+          ret
+        end
       end
-      o
     end
-    class_def(association_remove_all_method_name(name)) do
-      opts.associated_class.filter(key=>pk).update(key=>nil)
-      if arr = instance_variable_get(ivar)
-        ret = arr.dup
-        if reciprocal = opts.reciprocal
-          arr.each{|o| o.instance_variable_set(reciprocal, :null)} 
+    if opts[:one_to_one]
+      private name, :"#{name}_dataset"
+      n = name.to_s.singularize.to_sym
+      raise(Sequel::Error, "one_to_many association names should still be plural even when using the :one_to_one option") if n == name
+      class_def(n) do |*o|
+        objs = send(name, *o)
+        raise(Sequel::Error, "multiple values found for a one-to-one relationship") if objs.length > 1
+        objs.first
+      end
+      unless opts[:read_only]
+        private add_meth
+        class_def(:"#{n}=") do |o|
+          klass = opts.associated_class
+          model.db.transaction do
+            send(add_meth, o)
+            klass.filter(Sequel::SQL::BooleanExpression.new(:AND, {key=>pk}, ~{klass.primary_key=>o.pk}.sql_expr)).update(key=>nil)
+          end
         end
       end
-      instance_variable_set(ivar, [])
-      ret
     end
   end