sequel 3.11.0 → 3.12.0

data/lib/sequel/model/errors.rb

@@ -19,6 +19,11 @@ module Sequel
       def count
         values.inject(0){|m, v| m + v.length}
       end
+       
+      # Return true if there are no error messages, false otherwise.
+      def empty?
+        count == 0
+      end
       
       # Returns an array of fully-formatted error messages.
       def full_messages
@@ -32,7 +37,9 @@ module Sequel
       # Returns the array of errors for the given attribute, or nil
       # if there are no errors for the attribute.
       def on(att)
-        self[att] if has_key?(att)
+        if v = fetch(att, nil) and !v.empty?
+          v
+        end
       end
     end
   end

data/lib/sequel/plugins/active_model.rb

@@ -7,6 +7,14 @@ module Sequel
     # allow the full support of Sequel::Model objects in Rails 3.
     # This plugin requires active_model in order to use
     # ActiveModel::Naming.
+    # 
+    # Usage:
+    #
+    #   # Make all subclasses active_model compliant (called before loading subclasses)
+    #   Sequel::Model.plugin :active_model
+    #
+    #   # Make the Album class active_model compliant
+    #   Album.plugin :active_model
     module ActiveModel
       ClassMethods = ::ActiveModel::Naming
 

data/lib/sequel/plugins/association_pks.rb

@@ -0,0 +1,87 @@
+module Sequel
+  module Plugins
+    # The association_pks plugin adds the association_pks and association_pks=
+    # instance methods to the model class for each association added.  These
+    # methods allow for easily returning the primary keys of the associated
+    # objects, and easily modifying the associated objects to set the primary
+    # keys to just the ones given:
+    #
+    #   Artist.one_to_many :albums
+    #   artist = Artist[1]
+    #   artist.album_pks # [1, 2, 3]
+    #   artist.album_pks = [2, 4]
+    #   artist.album_pks # [2, 4]
+    #
+    # Note that it uses the singular form of the association name. Also note
+    # that the setter both associates to new primary keys not in the assocation
+    # and disassociated from primary keys not provided to the method.
+    #
+    # This plugin makes modifications directly to the underlying tables,
+    # it does not create or return any model objects, and therefore does
+    # not call any callbacks.  If you have any association callbacks,
+    # you probably should not use the setter methods.
+    #
+    # This plugin only works with singular primary keys, it does not work
+    # with composite primary keys.
+    # 
+    # Usage:
+    #
+    #   # Make all model subclass *_to_many associations have association_pks
+    #   # methods (called before loading subclasses)
+    #   Sequel::Model.plugin :association_pks
+    #
+    #   # Make the Album *_to_many associations have association_pks
+    #   # methods (called before the association methods)
+    #   Album.plugin :association_pks
+    module AssociationPks
+      module ClassMethods
+        private
+
+        # Define a association_pks method using the block for the association reflection 
+        def def_association_pks_getter(opts, &block)
+          association_module_def(:"#{singularize(opts[:name])}_pks", &block)
+        end
+
+        # Define a association_pks= method using the block for the association reflection,
+        # if the association is not read only.
+        def def_association_pks_setter(opts, &block)
+          association_module_def(:"#{singularize(opts[:name])}_pks=", &block) unless opts[:read_only]
+        end
+
+        # Add a getter that checks the join table for matching records and
+        # a setter that deletes from or inserts into the join table.
+        def def_many_to_many(opts)
+          super
+          def_association_pks_getter(opts) do
+            _join_table_dataset(opts).filter(opts[:left_key]=>send(opts[:left_primary_key])).select_map(opts[:right_key])
+          end
+          def_association_pks_setter(opts) do |pks|
+            checked_transaction do
+              ds = _join_table_dataset(opts).filter(opts[:left_key]=>send(opts[:left_primary_key]))
+              ds.exclude(opts[:right_key]=>pks).delete
+              pks -= ds.select_map(opts[:right_key])
+              pks.each{|pk| ds.insert(opts[:left_key]=>send(opts[:left_primary_key]), opts[:right_key]=>pk)}
+            end
+          end
+        end
+
+        # Add a getter that checks the association dataset and a setter
+        # that updates the associated table.
+        def def_one_to_many(opts)
+          super
+          return if opts[:type] == :one_to_one
+          def_association_pks_getter(opts) do
+            send(opts.dataset_method).select_map(opts[:primary_key])
+          end
+          def_association_pks_setter(opts) do |pks|
+            checked_transaction do
+              ds = send(opts.dataset_method)
+              ds.unfiltered.filter(opts[:primary_key]=>pks).update(opts[:key]=>pk)
+              ds.exclude(opts[:primary_key]=>pks).update(opts[:key]=>nil)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/association_proxies.rb

@@ -5,6 +5,14 @@ module Sequel
     # method returns a dataset.  This plugin makes the association method return a proxy
     # that will load the association and call a method on the association array if sent
     # an array method, and otherwise send the method to the association's dataset.
+    # 
+    # Usage:
+    #
+    #   # Use association proxies in all model subclasses (called before loading subclasses)
+    #   Sequel::Model.plugin :association_proxies
+    #
+    #   # Use association proxies in a specific model subclass
+    #   Album.plugin :association_proxies
     module AssociationProxies
       # A proxy for the association.  Calling an array method will load the
       # associated objects and call the method on the associated object array.

data/lib/sequel/plugins/boolean_readers.rb

@@ -4,14 +4,20 @@ module Sequel
     # for boolean columns, which provide a nicer API.  By default, the accessors
     # are created for all columns of type :boolean.  However, you can provide a
     # block to the plugin to change the criteria used to determine if a
-    # column is boolean:
+    # column is boolean.  The block is yielded with the column symbol for each
+    # column in the models dataset.
     #
-    #   Sequel::Model.plugin(:boolean_readers){|c| db_schema[c][:db_type] =~ /\Atinyint/}
+    # Usage:
     #
-    # This may be useful if you are using MySQL and have some tinyint columns
-    # that represent booleans and others that represent integers.  You can turn
-    # the convert_tinyint_to_bool setting off and use the attribute methods for
-    # the integer value and the attribute? methods for the boolean value.
+    #   # Add boolean attribute? methods for all columns of type :boolean
+    #   # in all model subclasses (called before loading subclasses)
+    #   Sequel::Model.plugin :boolean_readers
+    #
+    #   # Add boolean readers for all tinyint columns in the Album class
+    #   Album.plugin(:boolean_readers){|c| db_schema[c][:db_type] =~ /\Atinyint/}
+    #
+    #   # Add a boolean reader for a specific columns in the Artist class
+    #   Artist.plugin(:boolean_readers){|c| [:column1, :column2, :column3].include?(c)}
     module BooleanReaders
       # Default proc for determining if given column is a boolean, which
       # just checks that the :type is boolean.

data/lib/sequel/plugins/caching.rb

@@ -2,12 +2,7 @@ module Sequel
   module Plugins
     # Sequel's built-in caching plugin supports caching to any object that
     # implements the Ruby-Memcache API (or memcached API with the :ignore_exceptions
-    # option).  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:
+    # option):
     #
     #    cache_store.set(key, obj, time) # Associate the obj with the given key
     #                                    # in the cache for the time (specified
@@ -24,6 +19,18 @@ module Sequel
     #
     # Note that only Model.[] method calls with a primary key argument are cached
     # using this plugin.
+    # 
+    # Usage:
+    #
+    #   # Make all subclasses use the same cache (called before loading subclasses)
+    #   # using the Ruby-Memcache API, with the cache stored in the CACHE constant
+    #   Sequel::Model.plugin :caching, CACHE
+    #
+    #   # Make the Album class use the cache with a 30 minute time-to-live
+    #   Album.plugin :caching, CACHE, :ttl=>1800
+    #
+    #   # Make the Artist class use a cache with the memcached protocol
+    #   Artist.plugin :caching, MEMCACHED_CACHE, :ignore_exceptions=>true
     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.
@@ -105,8 +112,8 @@ module Sequel
       module InstanceMethods
         # Remove the object from the cache when updating
         def before_update
-          return false if super == false
           cache_delete
+          super
         end
 
         # Return a key unique to the underlying record for caching, based on the

data/lib/sequel/plugins/class_table_inheritance.rb

@@ -5,11 +5,11 @@ module Sequel
     # unique to that model class (or subclass hierarchy) being stored in the related
     # table.  For example, with this hierarchy:
     #
-    #                        Employee
-    #                       /        \ 
-    #                    Staff     Manager
-    #                                 |
-    #                             Executive
+    #       Employee
+    #      /        \ 
+    #   Staff     Manager
+    #                |
+    #            Executive
     #
     # the following database schema may be used (table - columns):
     #
@@ -54,6 +54,16 @@ module Sequel
     #   a = Employee.all # [<#Staff>, <#Manager>, <#Executive>]
     #   a.first.values # {:id=>1, name=>'S', :kind=>'Staff'}
     #   a.first.manager_id # Loads the manager_id attribute from the database
+    # 
+    # Usage:
+    #
+    #   # Set up class table inheritance in the parent class
+    #   # (Not in the subclasses)
+    #   Employee.plugin :class_table_inheritance
+    #
+    #   # Set the +kind+ column to hold the class name, and
+    #   # set the subclass table to map to for each subclass 
+    #   Employee.plugin :class_table_inheritance, :key=>:kind, :table_map=>{:Staff=>:staff}
     module ClassTableInheritance
       # The class_table_inheritance plugin requires the lazy_attributes plugin
       # to handle lazily-loaded attributes for subclass instances returned
@@ -71,10 +81,6 @@ module Sequel
       # * :table_map - Hash with class name symbol keys and table name symbol
       #   values.  Necessary if the implicit table name for the model class
       #   does not match the database table name
-      # Example:
-      #   class Employee < Sequel::Model
-      #     plugin :class_table_inheritance, :key=>:kind, :table_map=>{:Staff=>:staff}
-      #   end
       def self.configure(model, opts={}, &block)
         model.instance_eval do
           m = method(:constantize)

data/lib/sequel/plugins/composition.rb

@@ -9,7 +9,8 @@ module Sequel
     # to deal with Date objects in your ruby code.  This can be handled
     # with:
     #
-    #   Model.composition :date, :mapping=>[:year, :month, :day]
+    #   Album.plugin :composition
+    #   Album.composition :date, :mapping=>[:year, :month, :day]
     #
     # The :mapping option is optional, but you can define custom
     # composition and decomposition procs via the :composer and

data/lib/sequel/plugins/force_encoding.rb

@@ -10,12 +10,15 @@ module Sequel
     # 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
+    # Usage:
+    #
+    #   # Force all strings to be UTF8 encoded in a all model subclasses
+    #   # (called before loading subclasses)
+    #   Sequel::Model.plugin :force_encoding, 'UTF-8'
+    #
+    #   # Force the encoding for the Album model to UTF8
+    #   Album.plugin :force_encoding
+    #   Album.forced_encoding = 'UTF-8'
     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
@@ -69,4 +72,4 @@ module Sequel
 end
 else
   raise LoadError, 'ForceEncoding plugin only works on Ruby 1.9+'
-end
+end

data/lib/sequel/plugins/hook_class_methods.rb

@@ -23,6 +23,14 @@ module Sequel
     # 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.
+    # 
+    # Usage:
+    #
+    #   # Allow use of hook class methods in all model subclasses (called before loading subclasses)
+    #   Sequel::Model.plugin :hook_class_methods
+    #
+    #   # Allow the use of hook class methods in the Album class
+    #   Album.plugin :hook_class_methods
     module HookClassMethods
       # Set up the hooks instance variable in the model.
       def self.apply(model)
@@ -44,7 +52,7 @@ module Sequel
         # 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
+        # If any before 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,
@@ -66,7 +74,7 @@ module Sequel
           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__)
+            class_eval("def #{hook}; model.hook_blocks(:#{hook}){|b| return false if instance_eval(&b) == false}; end", __FILE__, __LINE__)
           end
         end
     
@@ -111,15 +119,8 @@ module Sequel
       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
+        Model::BEFORE_HOOKS.each{|h| class_eval("def #{h}; model.hook_blocks(:#{h}){|b| return false if instance_eval(&b) == false}; super; end", __FILE__, __LINE__)}
+        Model::AFTER_HOOKS.each{|h| class_eval("def #{h}; super; model.hook_blocks(:#{h}){|b| instance_eval(&b)}; end", __FILE__, __LINE__)}
       end
     end
   end

data/lib/sequel/plugins/identity_map.rb

@@ -21,6 +21,15 @@ module Sequel
     #
     # 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.
+    # 
+    # Usage:
+    #
+    #   # Use an identity map that will affect all model classes (called before loading subclasses)
+    #   Sequel::Model.plugin :identity_map
+    #
+    #   # Use an identity map just for the Album class
+    #   Album.plugin :identity_map
+    #   # would need to do Album.with_identity_map{} to use the identity map
     module IdentityMap
       module ClassMethods
         # Returns the current thread-local identity map.  Should be a hash if

data/lib/sequel/plugins/instance_hooks.rb

@@ -11,19 +11,28 @@ module Sequel
     # false, no more instance level before hooks are called and false is returned.
     #
     # Instance level hooks are cleared when the object is saved successfully.
+    # 
+    # Usage:
+    #
+    #   # Add the instance hook methods to all model subclass instances (called before loading subclasses)
+    #   Sequel::Model.plugin :instance_hooks
+    #
+    #   # Add the instance hook methods just to Album instances
+    #   Album.plugin :instance_hooks
     module InstanceHooks
       module InstanceMethods 
-        HOOKS = Sequel::Model::HOOKS - [:after_initialize]
+        BEFORE_HOOKS = Sequel::Model::BEFORE_HOOKS
+        AFTER_HOOKS = Sequel::Model::AFTER_HOOKS - [:after_initialize]
+        HOOKS = BEFORE_HOOKS + AFTER_HOOKS
         HOOKS.each{|h| class_eval("def #{h}_hook(&block); add_instance_hook(:#{h}, &block) end", __FILE__, __LINE__)}
         
-        BEFORE_HOOKS, AFTER_HOOKS = HOOKS.partition{|hook| hook.to_s =~ /\Abefore_/}
-        BEFORE_HOOKS.each{|h| class_eval("def #{h}; run_instance_hooks(:#{h}) == false ? false : super end", __FILE__, __LINE__)}
-        AFTER_HOOKS.each{|h| class_eval("def #{h}; super; run_instance_hooks(:#{h}) end", __FILE__, __LINE__)}
+        BEFORE_HOOKS.each{|h| class_eval("def #{h}; run_before_instance_hooks(:#{h}) == false ? false : super end", __FILE__, __LINE__)}
+        (AFTER_HOOKS - [:after_save]).each{|h| class_eval("def #{h}; super; run_after_instance_hooks(:#{h}) end", __FILE__, __LINE__)}
         
         # Clear the instance level hooks after saving the object.
         def after_save
           super
-          run_instance_hooks(:after_save)
+          run_after_instance_hooks(:after_save)
           @instance_hooks.clear if @instance_hooks
         end
         
@@ -42,14 +51,15 @@ module Sequel
           @instance_hooks[hook] ||= []
         end
         
-        # Run all hook blocks of the given hook type.  If a before hook,
-        # immediately return false if any hook block call returns false.
-        def run_instance_hooks(hook)
-          if BEFORE_HOOKS.include?(hook)
-            instance_hooks(hook).each{|b| return false if b.call == false}
-          else
-            instance_hooks(hook).each{|b| b.call}
-          end
+        # Run all hook blocks of the given hook type.
+        def run_after_instance_hooks(hook)
+          instance_hooks(hook).each{|b| b.call}
+        end
+
+        # Run all hook blocks of the given hook type.  If a hook block returns false,
+        # immediately return false without running the remaining blocks.
+        def run_before_instance_hooks(hook)
+          instance_hooks(hook).each{|b| return false if b.call == false}
         end
       end
     end

data/lib/sequel/plugins/lazy_attributes.rb

@@ -16,6 +16,9 @@ module Sequel
     #       a.review
     #     end
     #   end
+    #
+    #   # You can specify multiple columns to lazily load:
+    #   Album.plugin :lazy_attributes, :review, :tracklist
     module LazyAttributes
       # Lazy attributes requires the identity map and tactical eager loading plugins
       def self.apply(model, *attrs)
@@ -67,7 +70,7 @@ module Sequel
         # the attribute for the current object.
         def lazy_attribute_lookup(a)
           primary_key = model.primary_key
-          model.select(*(Array(primary_key) + [a])).filter(primary_key=>retrieved_with.map{|o| o.pk}.sql_array).all if model.identity_map && retrieved_with
+          model.select(*(Array(primary_key) + [a])).filter(primary_key=>::Sequel::SQL::SQLArray.new(retrieved_with.map{|o| o.pk})).all if model.identity_map && retrieved_with
           values[a] = this.select(a).first[a] unless values.include?(a)
           values[a]
         end

data/lib/sequel/plugins/many_through_many.rb

@@ -8,6 +8,7 @@ module Sequel
     #
     # The many_through_many plugin would allow this:
     #
+    #    Artist.plugin :many_through_many
     #    Artist.many_through_many :tags, [[:albums_artists, :artist_id, :album_id], [:albums, :id, :id], [:albums_tags, :album_id, :tag_id]]
     #
     # Which will give you the tags for all of the artist's albums.
@@ -28,6 +29,19 @@ module Sequel
     #   # All tracks on albums by this artist
     #   Artist.many_through_many :tracks, [[:albums_artists, :artist_id, :album_id], [:albums, :id, :id]], \
     #    :right_primary_key=>:album_id
+    #
+    # Often you don't want the current object to appear in the array of associated objects.  This is easiest to handle via an :after_load hook:
+    # 
+    #   Artist.many_through_many :artists, [[:albums_artists, :artist_id, :album_id], [:albums, :id, :id], [:albums_artists, :album_id, :artist_id]],
+    #     :after_load=>proc{|artist, associated_artists| associated_artists.delete(artist)}
+    #
+    # You can also handle it by adding a dataset block that excludes the current record (so it won't be retrieved at all), but
+    # that won't work when eagerly loading, which is why the :after_load proc is recommended instead.
+    #
+    # It's also common to not want duplicate records, in which case the :distinct option can be used:
+    # 
+    #   Artist.many_through_many :artists, [[:albums_artists, :artist_id, :album_id], [:albums, :id, :id], [:albums_artists, :album_id, :artist_id]],
+    #    :distinct=>true
     module ManyThroughMany
       # The AssociationReflection subclass for many_through_many associations.
       class ManyThroughManyAssociationReflection < Sequel::Model::Associations::ManyToManyAssociationReflection
@@ -165,15 +179,15 @@ module Sequel
           end
 
           left_key_alias = opts[:left_key_alias] ||= opts.default_associated_key_alias
-          opts[:eager_loader] ||= lambda do |key_hash, records, associations|
-            h = key_hash[left_pk]
-            records.each{|object| object.associations[name] = []}
+          opts[:eager_loader] ||= lambda do |eo|
+            h = eo[:key_hash][left_pk]
+            eo[:rows].each{|object| object.associations[name] = []}
             ds = opts.associated_class 
             opts.reverse_edges.each{|t| ds = ds.join(t[:table], Array(t[:left]).zip(Array(t[:right])), :table_alias=>t[:alias])}
             ft = opts[:final_reverse_edge]
             conds = uses_lcks ? [[left_keys.map{|k| SQL::QualifiedIdentifier.new(ft[:table], k)}, SQL::SQLArray.new(h.keys)]] : [[left_key, h.keys]]
             ds = ds.join(ft[:table], Array(ft[:left]).zip(Array(ft[:right])) + conds, :table_alias=>ft[:alias])
-            model.eager_loading_dataset(opts, ds, Array(opts.select), associations).all do |assoc_record|
+            model.eager_loading_dataset(opts, ds, Array(opts.select), eo[:associations], eo).all do |assoc_record|
               hash_key = if uses_lcks
                 left_key_alias.map{|k| assoc_record.values.delete(k)}
               else