sequel 3.4.0 → 3.5.0

data/lib/sequel/plugins/force_encoding.rb

@@ -0,0 +1,61 @@
+if RUBY_VERSION >= '1.9.0'
+module Sequel
+  module Plugins
+    # The ForceEncoding plugin allows you force specific encodings for all
+    # strings that are used by the model.  When model instances are loaded
+    # from the database, all values in the hash that are strings are
+    # forced to the given encoding.  Whenever you update a model column
+    # attribute, the resulting value is forced to a given encoding if the
+    # value is a string.  There are two ways to specify the encoding.  You
+    # 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
+    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
+      # forced encoding is overruled, even if no encoding is given when calling
+      # the plugin.
+      def self.configure(model, encoding=nil)
+        model.forced_encoding = encoding
+      end
+      
+      module ClassMethods
+        # The string encoding to force on a column string values
+        attr_accessor :forced_encoding
+        
+        # Copy the forced_encoding value into the subclass
+        def inherited(subclass)
+          super
+          subclass.forced_encoding = forced_encoding
+        end
+        
+        # Force the encoding of all strings for the given row to the model's
+        # forced_encoding.
+        def load(row)
+          row.values.each{|v| v.force_encoding(forced_encoding) if v.is_a?(String)} if forced_encoding
+          super
+        end
+      end
+    
+      module InstanceMethods
+        private
+        
+        # Force the encoding of all returned strings to the model's forced_encoding.
+        def typecast_value(column, value)
+          s = super
+          s.force_encoding(model.forced_encoding) if s.is_a?(String) && model.forced_encoding
+          s
+        end
+      end
+    end
+  end
+end
+else
+  raise LoadError, 'ForceEncoding plugin only works on Ruby 1.9+'
+end

data/lib/sequel/plugins/many_through_many.rb

@@ -37,6 +37,12 @@ module Sequel
         def associated_key_table
           self[:associated_key_table] = self[:final_reverse_edge][:alias]
         end
+        
+        # The default associated key alias(es) to use when eager loading
+        # associations via eager.
+        def default_associated_key_alias
+          self[:uses_left_composite_keys] ? (0...self[:through].first[:left].length).map{|i| :"x_foreign_key_#{i}_x"} : :x_foreign_key_x
+        end
 
         # The list of joins to use when eager graphing
         def edges
@@ -103,16 +109,22 @@ module Sequel
         #   Must be an array, with elements that are either 3 element arrays, or hashes with keys :table, :left, and :right.
         #   The required entries in the array/hash are:
         #   * :table (first array element) - The name of the table to join.
-        #   * :left (middle array element) - The key joining the table to the previous table
-        #   * :right (last array element) - The key joining the table to the next table
+        #   * :left (middle array element) - The key joining the table to the previous table. Can use an
+        #     array of symbols for a composite key association.
+        #   * :right (last array element) - The key joining the table to the next table. Can use an
+        #     array of symbols for a composite key association.
         #   If a hash is provided, the following keys are respected when using eager_graph:
         #   * :block - A proc to use as the block argument to join.
         #   * :conditions - Extra conditions to add to the JOIN ON clause.  Must be a hash or array of two pairs.
         #   * :join_type - The join type to use for the join, defaults to :left_outer.
         #   * :only_conditions - Conditions to use for the join instead of the ones specified by the keys.
         # * opts - The options for the associaion.  Takes the same options as associate, and supports these additional options:
-        #   * :left_primary_key - column in current table that the first :left option in through points to, as a symbol. Defaults to primary key of current table. 
-        #   * :right_primary_key - column in associated table that the final :right option in through points to, as a symbol. Defaults to primary key of the associated table.
+        #   * :left_primary_key - column in current table that the first :left option in
+        #     through points to, as a symbol. Defaults to primary key of current table. Can use an
+        #     array of symbols for a composite key association.
+        #   * :right_primary_key - column in associated table that the final :right option in 
+        #     through points to, as a symbol. Defaults to primary key of the associated table.  Can use an
+        #     array of symbols for a composite key association.
         #   * :uniq - Adds a after_load callback that makes the array of objects unique.
         def many_through_many(name, through, opts={}, &block)
           associate(:many_through_many, name, opts.merge(:through=>through), &block)
@@ -141,12 +153,15 @@ module Sequel
           end
 
           left_key = opts[:left_key] = opts[:through].first[:left]
+          uses_lcks = opts[:uses_left_composite_keys] = left_key.is_a?(Array)
+          left_keys = Array(left_key)
           left_pk = (opts[:left_primary_key] ||= self.primary_key)
+          left_pks = Array(left_pk)
           opts[:dataset] ||= lambda do
             ds = opts.associated_class
-            opts.reverse_edges.each{|t| ds = ds.join(t[:table], [[t[:left], t[:right]]], :table_alias=>t[:alias])}
+            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]
-            ds.join(ft[:table], [[ft[:left], ft[:right]], [left_key, send(left_pk)]], :table_alias=>ft[:alias])
+            ds.join(ft[:table],  Array(ft[:left]).zip(Array(ft[:right])) + left_keys.zip(left_pks.map{|k| send(k)}), :table_alias=>ft[:alias])
           end
 
           left_key_alias = opts[:left_key_alias] ||= opts.default_associated_key_alias
@@ -154,11 +169,17 @@ module Sequel
             h = key_hash[left_pk]
             records.each{|object| object.associations[name] = []}
             ds = opts.associated_class 
-            opts.reverse_edges.each{|t| ds = ds.join(t[:table], [[t[:left], t[:right]]], :table_alias=>t[:alias])}
+            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]
-            ds = ds.join(ft[:table], [[ft[:left], ft[:right]], [left_key, h.keys]], :table_alias=>ft[:alias])
+            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|
-              next unless objects = h[assoc_record.values.delete(left_key_alias)]
+              hash_key = if uses_lcks
+                left_key_alias.map{|k| assoc_record.values.delete(k)}
+              else
+                assoc_record.values.delete(left_key_alias)
+              end
+              next unless objects = h[hash_key]
               objects.each{|object| object.associations[name].push(assoc_record)}
             end
           end
@@ -172,11 +193,11 @@ module Sequel
           opts[:eager_grapher] ||= proc do |ds, assoc_alias, table_alias|
             iq = table_alias
             opts.edges.each do |t|
-              ds = ds.graph(t[:table], t.include?(:only_conditions) ? t[:only_conditions] : ([[t[:right], t[:left]]] + t[:conditions]), :select=>false, :table_alias=>ds.send(:eager_unique_table_alias, ds, t[:table]), :join_type=>t[:join_type], :implicit_qualifier=>iq, &t[:block])
+              ds = ds.graph(t[:table], t.include?(:only_conditions) ? t[:only_conditions] : (Array(t[:right]).zip(Array(t[:left])) + t[:conditions]), :select=>false, :table_alias=>ds.send(:eager_unique_table_alias, ds, t[:table]), :join_type=>t[:join_type], :implicit_qualifier=>iq, &t[:block])
               iq = nil
             end
             fe = opts[:final_edge]
-            ds.graph(opts.associated_class, use_only_conditions ? only_conditions : ([[opts.right_primary_key, fe[:left]]] + conditions), :select=>select, :table_alias=>assoc_alias, :join_type=>join_type, &graph_block)
+            ds.graph(opts.associated_class, use_only_conditions ? only_conditions : (Array(opts.right_primary_key).zip(Array(fe[:left])) + conditions), :select=>select, :table_alias=>assoc_alias, :join_type=>join_type, &graph_block)
           end
 
           def_association_dataset_methods(opts)

data/lib/sequel/plugins/nested_attributes.rb

@@ -84,7 +84,9 @@ module Sequel
           if reflection.returns_array?
             after_save_hook{send(reflection.add_method, obj)}
           else
-            before_save_hook{send(reflection.setter_method, obj.save)}
+            # Don't need to validate the object twice if :validate association option is not false
+            # and don't want to validate it at all if it is false.
+            before_save_hook{send(reflection.setter_method, obj.save(:validate=>false))}
           end
         end
         
@@ -155,13 +157,16 @@ module Sequel
           if obj = nested_attributes_find(reflection, pk)
             obj.set(attributes)
             after_validation_hook{validate_associated_object(reflection, obj)}
-            after_save_hook{obj.save}
+            # Don't need to validate the object twice if :validate association option is not false
+            # and don't want to validate it at all if it is false.
+            after_save_hook{obj.save(:validate=>false)}
           end
         end
         
         # Validate the given associated object, adding any validation error messages from the
         # given object to the parent object.
         def validate_associated_object(reflection, obj)
+          return if reflection[:validate] == false
           association = reflection[:name]
           obj.errors.full_messages.each{|m| errors.add(association, m)} unless obj.valid?
         end

data/lib/sequel/plugins/subclasses.rb

@@ -0,0 +1,45 @@
+module Sequel
+  module Plugins
+    # The Subclasses plugin keeps track of all subclasses of the
+    # current model class.  Direct subclasses are available via the
+    # subclasses method, and all descendent classes are available via the
+    # descendents method.
+    #
+    #   c = Class.new(Sequel::Model)
+    #   c.plugin :subclasses
+    #   sc1 = Class.new(c)
+    #   sc2 = Class.new(c)
+    #   ssc1 = Class.new(sc1)
+    #   c.subclasses    # [sc1, sc2]
+    #   sc1.subclasses  # [ssc1]
+    #   sc2.subclasses  # []
+    #   ssc1.subclasses # []
+    #   c.descendents   # [sc1, ssc1, sc2]
+    module Subclasses
+      # Initialize the subclasses instance variable for the model.
+      def self.apply(model, &block)
+        model.instance_variable_set(:@subclasses, [])
+      end
+
+      module ClassMethods
+        # All subclasses for the current model.  Does not
+        # include the model itself.
+        attr_reader :subclasses
+
+        # All descendent classes of this model.
+        def descendents
+          subclasses.map{|x| [x] + x.descendents}.flatten
+        end
+
+        # Add the subclass to this model's current subclasses,
+        # and initialize a new subclasses instance variable
+        # in the subclass.
+        def inherited(subclass)
+          super
+          subclasses << subclass
+          subclass.instance_variable_set(:@subclasses, [])
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/touch.rb

@@ -0,0 +1,118 @@
+module Sequel
+  module Plugins
+    # The touch plugin adds a touch method to model instances, which saves
+    # the object with a modified timestamp.  By default, it uses the
+    # :updated_at column, but you can set which column to use.
+    # It also supports touching of associations, so that when the current
+    # model object is updated or destroyed, the associated rows in the
+    # database can have their modified timestamp updated to the current
+    # timestamp.
+    #
+    # Since the instance touch method works on model instances,
+    # it uses Time.now for the timestamp.  The association touching works
+    # on datasets, so it updates all related rows in a single query, using
+    # the SQL standard CURRENT_TIMESTAMP.  Both of these can be overridden
+    # easily if necessary.
+    module Touch
+      # The default column to update when touching
+      TOUCH_COLUMN_DEFAULT = :updated_at
+
+      # Set the touch_column and touched_associations variables for the model.
+      # Options:
+      # * :associations - The associations to touch when a model instance is
+      #   updated or destroyed.  Can be a symbol for a single association,
+      #   a hash with association keys and column values, or an array of
+      #   symbols and/or hashes.  If a symbol is used, the column used
+      #   when updating the associated objects is the model's touch_column.
+      #   If a hash is used, the value is used as the column to update.
+      # * :column - The column to modify when touching a model instance.
+      def self.configure(model, opts={})
+        model.touch_column = opts[:column] || TOUCH_COLUMN_DEFAULT if opts[:column] || !model.touch_column
+        model.instance_variable_set(:@touched_associations, {})
+        model.touch_associations(opts[:associations]) if opts[:associations]
+      end
+
+      module ClassMethods
+        # The column to modify when touching a model instance, as a symbol.  Also used
+        # as the default column when touching associations, if
+        # the associations don't specify a column.
+        attr_accessor :touch_column
+
+        # A hash specifying the associations to touch when instances are
+        # updated or destroyed. Keys are association dataset method name symbols and values
+        # are column name symbols.
+        attr_reader :touched_associations
+
+        # Set the touch_column for the subclass to be the same as the current class.
+        # Also, create a copy of the touched_associations in the subclass.
+        def inherited(subclass)
+          super
+          subclass.touch_column = touch_column
+          subclass.instance_variable_set(:@touched_associations, touched_associations.dup)
+        end
+
+        # Add additional associations to be touched.  See the :association option
+        # of the Sequel::Plugin::Touch.configure method for the format of the associations
+        # arguments.
+        def touch_associations(*associations)
+          associations.flatten.each do |a|
+            a = {a=>touch_column} if a.is_a?(Symbol)
+            a.each do |k,v|
+              raise(Error, "invalid association: #{k}") unless r = association_reflection(k)
+              touched_associations[r.dataset_method] = v
+            end
+          end
+        end
+      end
+
+      module InstanceMethods
+        # Touch all of the model's touched_associations when destroying the object.
+        def after_destroy
+          super
+          touch_associations
+        end
+
+        # Touch all of the model's touched_associations when updating the object.
+        def after_update
+          super
+          touch_associations
+        end
+
+        # Touch the model object.  If a column is not given, use the model's touch_column
+        # as the column.  If the column to use is not one of the model's columns, just
+        # save the changes to the object instead of attempting to a value that doesn't
+        # exist.
+        def touch(column=nil)
+          if column
+            set(column=>touch_instance_value)
+          else
+            column = model.touch_column
+            set(column=>touch_instance_value) if columns.include?(column)
+          end
+          save_changes
+        end
+
+        private
+
+        # The value to use when modifying the touch column for the association datasets.  Uses
+        # the SQL standard CURRENT_TIMESTAMP.
+        def touch_association_value
+          Sequel::CURRENT_TIMESTAMP
+        end
+
+        # Directly update the database using the association dataset for each association.
+        def touch_associations
+          model.touched_associations.each do |meth, column|
+            send(meth).update(column=>touch_association_value)
+          end
+        end
+
+        # The value to use when modifying the touch column for the model instance.
+        # Uses Time.now to work well with typecasting.
+        def touch_instance_value
+          Time.now
+        end
+      end
+    end
+  end
+end

data/lib/sequel/plugins/typecast_on_load.rb

@@ -0,0 +1,61 @@
+module Sequel
+  module Plugins
+    # The TypecastOnLoad plugin exists because most of Sequel's database adapters don't
+    # have complete control over typecasting, and may return columns that aren't
+    # typecast correctly (with correct being defined as how the model object
+    # would typecast the same column values).
+    #
+    # This plugin modifies Model.load to call the setter methods (which typecast
+    # by default) for all columns given.  You can either specify the columns to
+    # typecast on load in the plugin call itself, or afterwards using 
+    # add_typecast_on_load_columns:
+    #
+    #   Album.plugin :typecast_on_load, :release_date, :record_date
+    #   # or:
+    #   Album.plugin :typecast_on_load
+    #   Album.add_typecast_on_load_columns :release_date, :record_date
+    #
+    # If the database returns release_date and record_date columns as strings
+    # instead of dates, this will ensure that if you access those columns through
+    # the model object, you'll get Date objects instead of strings.
+    module TypecastOnLoad
+      # Call add_typecast_on_load_columns on the passed column arguments.
+      def self.configure(model, *columns, &block)
+        model.instance_eval do
+          @typecast_on_load_columns ||= []
+          add_typecast_on_load_columns(*columns)
+        end
+      end
+
+      module ClassMethods
+        # The columns to typecast on load for this model.
+        attr_reader :typecast_on_load_columns
+
+        # Add additional columns to typecast on load for this model.
+        def add_typecast_on_load_columns(*columns)
+          @typecast_on_load_columns.concat(columns)
+        end
+
+        # Give the subclass a copy of the typecast on load columns.
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@typecast_on_load_columns, typecast_on_load_columns.dup)
+        end
+
+        # Call the setter method for each of the typecast on load columns,
+        # ensuring the model object will have the correct typecasting even
+        # if the database doesn't typecast the columns correctly.
+        def load(values)
+          o = super
+          typecast_on_load_columns.each do |c|
+            if v = values[c]
+              o.send("#{c}=", v)
+            end
+          end
+          o.changed_columns.clear
+          o
+        end
+      end
+    end
+  end
+end

data/lib/sequel/sql.rb

@@ -1,5 +1,8 @@
 module Sequel
   if RUBY_VERSION < '1.9.0'
+    # If on Ruby 1.8, create a Sequel::BasicObject class that is similar to the
+    # the Ruby 1.9 BasicObject class.  This is used in a few places where proxy
+    # objects are needed that respond to any method call.
     class BasicObject
       (instance_methods - %w"__id__ __send__ instance_eval == equal?").each{|m| undef_method(m)}
     end
@@ -137,9 +140,7 @@ module Sequel
       ComplexExpression::BITWISE_OPERATORS.each do |o|
         define_method(o) do |ce|
           case ce
-          when NumericExpression 
-            NumericExpression.new(o, self, ce)
-          when ComplexExpression
+          when BooleanExpression, StringExpression
             raise(Sequel::Error, "cannot apply #{o} to a non-numeric expression")
           else  
             NumericExpression.new(o, self, ce)
@@ -167,9 +168,7 @@ module Sequel
       ComplexExpression::BOOLEAN_OPERATOR_METHODS.each do |m, o|
         define_method(m) do |ce|
           case ce
-          when BooleanExpression
-            BooleanExpression.new(o, self, ce)
-          when ComplexExpression
+          when NumericExpression, StringExpression
             raise(Sequel::Error, "cannot apply #{o} to a non-boolean expression")
           else  
             BooleanExpression.new(o, self, ce)
@@ -296,9 +295,7 @@ module Sequel
       ComplexExpression::MATHEMATICAL_OPERATORS.each do |o|
         define_method(o) do |ce|
           case ce
-          when NumericExpression
-            NumericExpression.new(o, self, ce)
-          when ComplexExpression
+          when BooleanExpression, StringExpression
             raise(Sequel::Error, "cannot apply #{o} to a non-numeric expression")
           else  
             NumericExpression.new(o, self, ce)
@@ -372,25 +369,6 @@ module Sequel
       end
     end
 
-    class ComplexExpression
-      include AliasMethods
-      include CastMethods
-      include OrderMethods
-      include SubscriptMethods
-    end
-
-    class GenericExpression
-      include AliasMethods
-      include CastMethods
-      include OrderMethods
-      include ComplexExpressionMethods
-      include BooleanMethods
-      include NumericMethods
-      include StringMethods
-      include SubscriptMethods
-      include InequalityMethods
-    end
-
     ### Classes ###
 
     # Represents an aliasing of an expression/column to a given name.
@@ -475,8 +453,8 @@ module Sequel
           else
             BooleanExpression.new(OPERTATOR_INVERSIONS[op], *ce.args.dup)
           end
-        when ComplexExpression
-          raise(Sequel::Error, "operator #{ce.op} cannot be inverted")
+        when StringExpression, NumericExpression
+          raise(Sequel::Error, "cannot invert #{ce.inspect}")
         else
           BooleanExpression.new(:NOT, ce)
         end
@@ -541,6 +519,13 @@ module Sequel
       to_s_method :column_all_sql
     end
     
+    class ComplexExpression
+      include AliasMethods
+      include CastMethods
+      include OrderMethods
+      include SubscriptMethods
+    end
+
     # Represents constants or psuedo-constants (e.g. CURRENT_DATE) in SQL
     class Constant < GenericExpression
       # Create an object with the given table
@@ -551,6 +536,10 @@ module Sequel
       to_s_method :constant_sql, '@constant'
     end
     
+    # Holds default generic constants that can be referenced.  These
+    # are included in the Sequel top level module and are also available
+    # in this module which can be required at the top level to get
+    # direct access to the constants.
     module Constants
       CURRENT_DATE = Constant.new(:CURRENT_DATE)
       CURRENT_TIME = Constant.new(:CURRENT_TIME)
@@ -579,6 +568,18 @@ module Sequel
       to_s_method :function_sql
     end
     
+    class GenericExpression
+      include AliasMethods
+      include BooleanMethods
+      include CastMethods
+      include ComplexExpressionMethods
+      include InequalityMethods
+      include NumericMethods
+      include OrderMethods
+      include StringMethods
+      include SubscriptMethods
+    end
+
     # Represents an identifier (column or table). Can be used
     # to specify a Symbol with multiple underscores should not be
     # split, or for creating an identifier without using a symbol.