sequel 1.4.0 → 1.5.0

data/Rakefile

@@ -9,16 +9,10 @@ include FileUtils
 # Configuration
 ##############################################################################
 NAME = "sequel"
-VERS = "1.4.0"
+VERS = "1.5.0"
+SEQUEL_CORE_VERS= "1.5.0"
 CLEAN.include ["**/.*.sw?", "pkg/*", ".config", "doc/*", "coverage/*"]
-RDOC_OPTS = [
-  "--quiet", 
-  "--title", "Sequel: The Database Toolkit for Ruby",
-  "--opname", "index.html",
-  "--line-numbers", 
-  "--main", "README",
-  "--inline-source"
-]
+RDOC_OPTS = ["--quiet", "--line-numbers", "--inline-source"]
 
 ##############################################################################
 # RDoc
@@ -29,15 +23,14 @@ Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_dir = "doc/rdoc"
   rdoc.options += RDOC_OPTS
   rdoc.main = "README"
-  rdoc.title = "Sequel: The Database Toolkit for Ruby"
-  rdoc.rdoc_files.add ["README", "COPYING", "lib/sequel_model.rb", "lib/**/*.rb"]
+  rdoc.title = "Sequel: The Database Toolkit for Ruby: Model Classes"
+  rdoc.rdoc_files.add ["README", "COPYING", "lib/**/*.rb"]
 end
 
 ##############################################################################
 # Gem packaging
 ##############################################################################
 desc "Packages up Sequel."
-task :default => [:package]
 task :package => [:clean]
 
 spec = Gem::Specification.new do |s|
@@ -47,8 +40,7 @@ spec = Gem::Specification.new do |s|
   s.platform = Gem::Platform::RUBY
   s.has_rdoc = true
   s.extra_rdoc_files = ["README", "CHANGELOG", "COPYING"]
-  s.rdoc_options += RDOC_OPTS + 
-    ["--exclude", "^(examples|extras)\/", "--exclude", "lib/sequel_model.rb"]
+  s.rdoc_options += RDOC_OPTS + ["--exclude", "^(examples|extras)\/"]
   s.summary = "The Database Toolkit for Ruby: Model Classes"
   s.description = s.summary
   s.author = "Jeremy Evans"
@@ -63,8 +55,7 @@ spec = Gem::Specification.new do |s|
     s.platform = Gem::Platform::RUBY
   end
 
-  s.add_dependency("assistance", '>= 0.1.2')
-  s.add_dependency("sequel_core", '= 1.4.0')
+  s.add_dependency("sequel_core", "= #{SEQUEL_CORE_VERS}")
   
   s.files = %w(COPYING README Rakefile) + Dir.glob("{doc,spec,lib}/**/*")
 
@@ -119,6 +110,7 @@ Spec::Rake::SpecTask.new("spec") do |t|
 end
 
 desc "Run specs without coverage"
+task :default => [:spec_no_cov]
 Spec::Rake::SpecTask.new("spec_no_cov") do |t|
   fixRUBYLIB.call
   t.spec_files = FileList["spec/**/*_spec.rb"]

data/lib/sequel_model.rb

@@ -7,239 +7,15 @@ module Sequel
 end
 
 files = %w[
-  base hooks record schema associations 
-  caching plugins validations eager_loading
+  inflector inflections base hooks record schema associations 
+  caching plugins validations eager_loading deprecated
 ]
 dir = File.join(File.dirname(__FILE__), "sequel_model")
 files.each {|f| require(File.join(dir, f))}
 
 module Sequel
-  # == Sequel Models
-  # 
-  # Models in Sequel are based on the Active Record pattern described by Martin Fowler (http://www.martinfowler.com/eaaCatalog/activeRecord.html). A model class corresponds to a table or a dataset, and an instance of that class wraps a single record in the model's underlying dataset.
-  # 
-  # Model classes are defined as regular Ruby classes:
-  # 
-  #   DB = Sequel('sqlite:/blog.db')
-  #   class Post < Sequel::Model
-  #     set_dataset DB[:posts]
-  #   end
-  # 
-  # You can also use the shorthand form:
-  # 
-  #   DB = Sequel('sqlite:/blog.db')
-  #   class Post < Sequel::Model
-  #   end
-  # 
-  # === Model instances
-  # 
-  # Model instance are identified by a primary key. By default, Sequel assumes the primary key column to be :id. The Model#[] method can be used to fetch records by their primary key:
-  # 
-  #   post = Post[123]
-  # 
-  # The Model#pk method is used to retrieve the record's primary key value:
-  # 
-  #   post.pk #=> 123
-  # 
-  # Sequel models allow you to use any column as a primary key, and even composite keys made from multiple columns:
-  # 
-  #   class Post < Sequel::Model
-  #     set_primary_key [:category, :title]
-  #   end
-  # 
-  #   post = Post['ruby', 'hello world']
-  #   post.pk #=> ['ruby', 'hello world']
-  # 
-  # You can also define a model class that does not have a primary key, but then you lose the ability to update records.
-  # 
-  # A model instance can also be fetched by specifying a condition:
-  # 
-  #   post = Post[:title => 'hello world']
-  #   post = Post.find {:stamp < 10.days.ago}
-  # 
-  # === Iterating over records
-  # 
-  # A model class lets you iterate over specific records by acting as a proxy to the underlying dataset. This means that you can use the entire Dataset API to create customized queries that return model instances, e.g.:
-  # 
-  #   Post.filter(:category => 'ruby').each {|post| p post}
-  # 
-  # You can also manipulate the records in the dataset:
-  # 
-  #   Post.filter {:stamp < 7.days.ago}.delete
-  #   Post.filter {:title =~ /ruby/}.update(:category => 'ruby')
-  # 
-  # === Accessing record values
-  # 
-  # A model instances stores its values as a hash:
-  # 
-  #   post.values #=> {:id => 123, :category => 'ruby', :title => 'hello world'}
-  # 
-  # You can read the record values as object attributes:
-  # 
-  #   post.id #=> 123
-  #   post.title #=> 'hello world'
-  # 
-  # You can also change record values:
-  # 
-  #   post.title = 'hey there'
-  #   post.save
-  # 
-  # Another way to change values by using the #set method:
-  # 
-  #   post.set(:title => 'hey there')
-  # 
-  # === Creating new records
-  # 
-  # New records can be created by calling Model.create:
-  # 
-  #   post = Post.create(:title => 'hello world')
-  # 
-  # Another way is to construct a new instance and save it:
-  # 
-  #   post = Post.new
-  #   post.title = 'hello world'
-  #   post.save
-  # 
-  # You can also supply a block to Model.new and Model.create:
-  # 
-  #   post = Post.create {|p| p.title = 'hello world'}
-  # 
-  #   post = Post.new do |p|
-  #     p.title = 'hello world'
-  #     p.save
-  #   end
-  # 
-  # === Hooks
-  # 
-  # You can execute custom code when creating, updating, or deleting records by using hooks. The before_create and after_create hooks wrap record creation. The before_update and after_update wrap record updating. The before_save and after_save wrap record creation and updating. The before_destroy and after_destroy wrap destruction.
-  # 
-  # Hooks are defined by supplying a block:
-  # 
-  #   class Post < Sequel::Model
-  #     after_create do
-  #       set(:created_at => Time.now)
-  #     end
-  # 
-  #     after_destroy do
-  #       author.update_post_count
-  #     end
-  #   end
-  # 
-  # === Deleting records
-  # 
-  # You can delete individual records by calling #delete or #destroy. The only difference between the two methods is that #destroy invokes before_destroy and after_destroy hooks, while #delete does not:
-  # 
-  #   post.delete #=> bypasses hooks
-  #   post.destroy #=> runs hooks
-  # 
-  # Records can also be deleted en-masse by invoking Model.delete and Model.destroy. As stated above, you can specify filters for the deleted records:
-  # 
-  #   Post.filter(:category => 32).delete #=> bypasses hooks
-  #   Post.filter(:category => 32).destroy #=> runs hooks
-  # 
-  # Please note that if Model.destroy is called, each record is deleted 
-  # separately, but Model.delete deletes all relevant records with a single 
-  # SQL statement.
-  # 
-  # === Associations
-  # 
-  # Sequel provides macros for the three most common types of associations: 
-  # many_to_one, one_to_many and many_to_many (equivalent to ActiveRecord's
-  # belongs_to, has_many and has_and_belongs_to_many).
-  # 
-  # Associations are defined in similar fashion to ActiveRecord:
-  #
-  #   class Post < Sequel::Model
-  #     belongs_to :author
-  #   end
-  #
-  #   class Author < Sequel::Model
-  #     has_many :posts
-  #   end
-  # 
-  # Another way to define an association in a Sequel model is as a regular
-  # instance method:
-  # 
-  #   class Post < Sequel::Model
-  #     def author; Author[author_id]; end
-  #   end
-  # 
-  #   class Author < Sequel::Model
-  #     def posts; Post.filter(:author_id => pk); end
-  #   end
-  # 
-  # === Caching model instances with memcached
-  # 
-  # Sequel models can be cached using memcached based on their primary keys. The use of memcached can significantly reduce database load by keeping model instances in memory. The set_cache method is used to specify caching:
-  # 
-  #   require 'memcache'
-  #   CACHE = MemCache.new 'localhost:11211', :namespace => 'blog'
-  # 
-  #   class Author < Sequel::Model
-  #     set_cache CACHE, :ttl => 3600
-  #   end
-  # 
-  #   Author[333] # database hit
-  #   Author[333] # cache hit
-  # 
-  # === Extending the underlying dataset
-  # 
-  # The obvious way to add table-wide logic is to define class methods to the model class definition. That way you can define subsets of the underlying dataset, change the ordering, or perform actions on multiple records:
-  # 
-  #   class Post < Sequel::Model
-  #     def self.old_posts
-  #       filter {:stamp < 30.days.ago}
-  #     end
-  # 
-  #     def self.clean_old_posts
-  #       old_posts.delete
-  #     end
-  #   end
-  # 
-  # You can also implement table-wide logic by defining methods on the dataset:
-  # 
-  #   class Post < Sequel::Model
-  #     def dataset.old_posts
-  #       filter {:stamp < 30.days.ago}
-  #     end
-  # 
-  #     def dataset.clean_old_posts
-  #       old_posts.delete
-  #     end
-  #   end
-  # 
-  # This is the recommended way of implementing table-wide operations, and allows you to have access to your model API from filtered datasets as well:
-  # 
-  #   Post.filter(:category => 'ruby').clean_old_posts
-  # 
-  # Sequel models also provide a short hand notation for filters:
-  # 
-  #   class Post < Sequel::Model
-  #     subset(:old_posts) {:stamp < 30.days.ago}
-  #     subset :invisible, :visible => false
-  #   end
-  # 
-  # === Defining the underlying schema
-  # 
-  # Model classes can also be used as a place to define your table schema and control it. The schema DSL is exactly the same provided by Sequel::Schema::Generator:
-  # 
-  #   class Post < Sequel::Model
-  #     set_schema do
-  #       primary_key :id
-  #       text :title
-  #       text :category
-  #       foreign_key :author_id, :table => :authors
-  #     end
-  #   end
-  # 
-  # You can then create the underlying table, drop it, or recreate it:
-  # 
-  #   Post.table_exists?
-  #   Post.create_table
-  #   Post.drop_table
-  #   Post.create_table! # drops the table if it exists and then recreates it
-  # 
   class Model
+    extend Enumerable
     extend Associations
     # Returns a string representation of the model instance including
     # the class name and values.
@@ -249,7 +25,7 @@ module Sequel
     
     # Defines a method that returns a filtered dataset.
     def self.subset(name, *args, &block)
-      dataset.meta_def(name) {filter(*args, &block)}
+      def_dataset_method(name){filter(*args, &block)}
     end
     
     # Finds a single record according to the supplied filter, e.g.:
@@ -281,8 +57,6 @@ module Sequel
       find(cond) || create(cond)
     end
 
-    ############################################################################
-
     # Deletes all records in the model's table.
     def self.delete_all
       dataset.delete
@@ -292,33 +66,17 @@ module Sequel
     def self.destroy_all
       dataset.destroy
     end
-        
-    def self.is_dataset_magic_method?(m)
-      method_name = m.to_s
-      Sequel::Dataset::MAGIC_METHODS.each_key do |r|
-        return true if method_name =~ r
-      end
-      false
-    end
-    
-    def self.method_missing(m, *args, &block) #:nodoc:
-      Thread.exclusive do
-        if dataset.respond_to?(m) || is_dataset_magic_method?(m)
-          instance_eval("def #{m}(*args, &block); dataset.#{m}(*args, &block); end")
-        end
-      end
-      respond_to?(m) ? send(m, *args, &block) : super(m, *args)
-    end
 
-    # TODO: Comprehensive description goes here!
-    def self.join(*args)
-      table_name = dataset.opts[:from].first
-      dataset.join(*args).select(table_name.to_sym.ALL)
-    end
-    
-    # Returns an array containing all of the models records.
-    def self.all
-      dataset.all
-    end
+    # Add dataset methods via metaprogramming
+    DATASET_METHODS = %w'all avg count delete distinct eager eager_graph each each_page 
+       empty? except exclude filter first from_self full_outer_join graph 
+       group group_and_count group_by having import inner_join insert 
+       insert_multiple intersect interval invert_order join join_table last 
+       left_outer_join limit multi_insert naked order order_by order_more 
+       paginate print query range reverse_order right_outer_join select 
+       select_all select_more set set_graph_aliases single_value size to_csv 
+       transform union uniq unordered update where'
+
+    def_dataset_method *DATASET_METHODS
   end
 end

data/lib/sequel_model/associations.rb

@@ -10,10 +10,15 @@
 #     one_to_many :milestones
 #   end
 # 
-# The project class now has the following methods:
-# * Project#portfolio, Project#portfolio=
-# * Project#milestones, Project#add_milestone, Project#remove_milestone,
-#   Project#milestones_dataset
+# The project class now has the following instance methods:
+# * portfolio - Returns the associated portfolio
+# * portfolio=(obj) - Sets the associated portfolio to the object,
+#   but the change is not persisted until you save the record.
+# * milestones - Returns an array of associated milestones
+# * milestones_dataset - Returns a dataset that would return the associated
+#   milestones, allowing for further filtering/limiting/etc.
+# * add_milestone(obj) - Associates the passed milestone with this object
+# * remove_milestone(obj) - Removes the association with the passed milestone
 #
 # By default the classes for the associations are inferred from the association
 # name, so for example the Project#portfolio will return an instance of 
@@ -37,6 +42,8 @@
 #   one_to_many :attributes
 #   has_many :attributes
 module Sequel::Model::Associations
+  RECIPROCAL_ASSOCIATIONS = {:many_to_one=>:one_to_many, :one_to_many=>:many_to_one, :many_to_many=>:many_to_many}
+
   # Array of all association reflections
   def all_association_reflections
     association_reflections.values
@@ -66,11 +73,18 @@ module Sequel::Model::Associations
   # * *ALL types*:
   #   - :class - The associated class or its name. If not
   #     given, uses the association's name, which is camelized (and
-  #     singularized if type is :{one,many}_to_many)
+  #     singularized unless the type is :many_to_one)
   #   - :eager - The associations to eagerly load when loading the associated object.
   #     For many_to_one associations, this is ignored unless this association is
   #     being eagerly loaded, as it doesn't save queries unless multiple objects
   #     can be loaded at once.
+  #   - :reciprocal - the symbol name of the instance variable 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.
+  # * :one_to_many/:many_to_many:
+  #   - :order - the column(s) by which to order the association dataset.  Can be a
+  #     singular column or an array.
   # * :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".
@@ -78,12 +92,6 @@ 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".
-  #   - :reciprocal - the string name of the instance variable of the reciprocal many_to_one association,
-  #     if it exists.  By default, sequel will try to determine it by looking at the
-  #     associated model's assocations for a many_to_one association that matches
-  #     the current association's key.  Set to nil to not use a reciprocal.
-  #   - :order - the column(s) by which to order the association dataset.  Can be a
-  #     singular column or an array.
   # * :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
@@ -94,13 +102,11 @@ module Sequel::Model::Associations
   #   - :right_key - foreign key in join table that points to associated
   #     model's primary key, as a symbol.
   #   - :select - the attributes to select.  Defaults to the associated class's
-  #     table_name.*, which means it doesn't include the attributes from the join
+  #     table_name.*, which means it doesn't include the attributes from the
   #     join table.  If you want to include the join table attributes, you can
   #     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.
-  #   - :order - the column(s) by which to order the association dataset. Can be a
-  #     singular column or an array.
   def associate(type, name, opts = {}, &block)
     # check arguments
     raise ArgumentError unless [:many_to_one, :one_to_many, :many_to_many].include?(type) && Symbol === name
@@ -110,7 +116,7 @@ module Sequel::Model::Associations
 
     # deprecation
     if opts[:from]
-      STDERR << "The :from option is deprecated, please use the :class option instead.\r\n"
+      Sequel::Deprecation.deprecate("The :from option to Sequel::Model.associate is deprecated and will be removed in Sequel 2.0.  Use the :class option.")
       opts[:class] = opts[:from]
     end
 
@@ -139,12 +145,6 @@ module Sequel::Model::Associations
     association_reflections.keys
   end
 
-  # deprecated, please use many_to_one instead
-  def one_to_one(*args, &block)
-    STDERR << "one_to_one relation definitions are deprecated, please use many_to_one instead.\r\n"
-    many_to_one(*args, &block)
-  end
-
   # Shortcut for adding a one_to_many association, see associate
   def one_to_many(*args, &block)
     associate(:one_to_many, *args, &block)
@@ -224,7 +224,8 @@ module Sequel::Model::Associations
           ds = ds.eager(eager)
         end
         objs = ds.all
-        if reciprocal = self.class.send(:reciprocal_association, opts)
+        # Only one_to_many associations should set the reciprocal object
+        if (opts[:type] == :one_to_many) && (reciprocal = model.send(:reciprocal_association, opts))
           objs.each{|o| o.instance_variable_set(reciprocal, self)}
         end
         instance_variable_set(ivar, objs)
@@ -239,9 +240,11 @@ module Sequel::Model::Associations
     ivar = association_ivar(name)
     class_def(name) do |*reload|
       if !reload[0] && obj = instance_variable_get(ivar)
-        obj
+        obj == :null ? nil : obj
       else
-        instance_variable_set(ivar, instance_eval(&block))
+        obj = instance_eval(&block)
+        instance_variable_set(ivar, obj || :null)
+        obj
       end
     end
   end
@@ -249,6 +252,7 @@ module Sequel::Model::Associations
   # Adds many_to_many association instance methods
   def def_many_to_many(name, opts)
     assoc_class = method(:associated_class) # late binding of association dataset
+    recip_assoc = method(:reciprocal_association) # late binding of the reciprocal association
     ivar = association_ivar(name)
     left = (opts[:left_key] ||= default_remote_key)
     right = (opts[:right_key] ||= :"#{name.to_s.singularize}_id")
@@ -259,7 +263,7 @@ module Sequel::Model::Associations
     def_association_dataset_methods(name, opts) do
       klass = assoc_class[opts]
       key = (opts[:right_primary_key] ||= :"#{klass.table_name}__#{klass.primary_key}")
-      selection = (opts[:select] ||= klass.table_name.all)
+      selection = (opts[:select] ||= klass.table_name.*)
       klass.select(selection).inner_join(join_table, right => key, left => pk)
     end
 
@@ -268,6 +272,10 @@ module Sequel::Model::Associations
       if arr = instance_variable_get(ivar)
         arr.push(o)
       end
+      if (reciprocal = recip_assoc[opts]) && (list = o.instance_variable_get(reciprocal)) \
+         && !(list.include?(self))
+        list.push(self)
+      end
       o
     end
     class_def(association_remove_method_name(name)) do |o|
@@ -275,6 +283,9 @@ module Sequel::Model::Associations
       if arr = instance_variable_get(ivar)
         arr.delete(o)
       end
+      if (reciprocal = recip_assoc[opts]) && (list = o.instance_variable_get(reciprocal))
+        list.delete(self)
+      end
       o
     end
   end
@@ -282,6 +293,7 @@ module Sequel::Model::Associations
   # Adds many_to_one association instance methods
   def def_many_to_one(name, opts)
     assoc_class = method(:associated_class) # late binding of association dataset
+    recip_assoc = method(:reciprocal_association) # late binding of the reciprocal association
     ivar = association_ivar(name)
     
     key = (opts[:key] ||= :"#{name}_id")
@@ -289,14 +301,25 @@ module Sequel::Model::Associations
     
     def_association_getter(name) {(fk = send(key)) ? assoc_class[opts][fk] : nil}
     class_def(:"#{name}=") do |o|
+      old_val = instance_variable_get(ivar) if reciprocal = recip_assoc[opts]
       instance_variable_set(ivar, 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)
+        end
+        if o && (list = o.instance_variable_get(reciprocal)) && !(list.include?(self))
+          list.push(self) 
+        end
+      end
+      o
     end
   end
   
   # Adds one_to_many association instance methods
   def def_one_to_many(name, opts)
     assoc_class = method(:associated_class) # late binding of association dataset
+    recip_assoc = method(:reciprocal_association) # late binding of the reciprocal association
     ivar = association_ivar(name)
     key = (opts[:key] ||= default_remote_key)
     opts[:class_name] ||= name.to_s.singularize.camelize
@@ -309,6 +332,9 @@ module Sequel::Model::Associations
       if arr = instance_variable_get(ivar)
         arr.push(o)
       end
+      if reciprocal = recip_assoc[opts]
+        o.instance_variable_set(reciprocal, self)
+      end
       o
     end
     class_def(association_remove_method_name(name)) do |o|
@@ -317,13 +343,16 @@ module Sequel::Model::Associations
       if arr = instance_variable_get(ivar)
         arr.delete(o)
       end
+      if reciprocal = recip_assoc[opts]
+        o.instance_variable_set(reciprocal, :null)
+      end
       o
     end
   end
   
   # Name symbol for default join table
   def default_join_table_name(opts)
-    ([opts[:class_name], self.name.demodulize]. \
+    ([opts[:class_name].demodulize, name.demodulize]. \
       map{|i| i.pluralize.underscore}.sort.join('_')).to_sym
   end
   
@@ -334,18 +363,26 @@ module Sequel::Model::Associations
 
   # Sets the reciprocal association variable in the reflection, if one exists
   def reciprocal_association(reflection)
-    if reflection[:type] != :one_to_many
-      nil
-    elsif reflection.include?(:reciprocal)
-      reflection[:reciprocal]
+    return reflection[:reciprocal] if reflection.include?(:reciprocal)
+    reciprocal_type = ::Sequel::Model::Associations::RECIPROCAL_ASSOCIATIONS[reflection[:type]]
+    if reciprocal_type == :many_to_many
+      left_key = reflection[:left_key]
+      right_key = reflection[:right_key]
+      join_table = reflection[:join_table]
+      associated_class(reflection).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 reflection[:reciprocal] = association_ivar(assoc_reflect[:name]).to_s.freeze
+        end
+      end
     else
       key = reflection[:key]
       associated_class(reflection).all_association_reflections.each do |assoc_reflect|
-        if assoc_reflect[:type] == :many_to_one && assoc_reflect[:key] == key
-          return reflection[:reciprocal] = "@#{assoc_reflect[:name]}".freeze
+        if assoc_reflect[:type] == reciprocal_type && assoc_reflect[:key] == key
+          return reflection[:reciprocal] = association_ivar(assoc_reflect[:name])
         end
       end
-      reflection[:reciprocal] = nil
     end
+    reflection[:reciprocal] = nil
   end
 end