dm-core 0.9.11 → 0.10.0

data/lib/dm-core/type.rb

@@ -6,109 +6,144 @@ module DataMapper
   # and therefore is responsible for providing those methods.
   #
   # To see complete list of supported types, see documentation for
-  # DataMapper::Property::TYPES
+  # Property::PRIMITIVES. dm-types library provides less common
+  # types such as ip address, uuid, json, yaml, uri, slug, version,
+  # file path, bcrypt hash and so forth.
   #
   # == Defining new Types
   # To define a new type, subclass DataMapper::Type, pick ruby primitive, and
   # set the options for this type.
   #
-  #   class MyType < DataMapper::Type
-  #     primitive String
-  #     size 10
+  #   class LowerCase < DataMapper::Type
+  #     primitive        String
+  #     auto_validation  true
+  #     length           255
   #   end
   #
-  # Following this, you will be able to use MyType as a type for any given
+  # Following this, you will be able to use LowerCase as a type for any given
   # property. If special materialization and serialization is required,
   # override the class methods
   #
-  #   class MyType < DataMapper::Type
-  #     primitive String
-  #     size 10
+  #   class LowerCase < DataMapper::Type
+  #     primitive        String
+  #     auto_validation  true
+  #     length           255
   #
   #     def self.dump(value, property)
-  #       <work some magic>
+  #       return nil unless value
+  #       value.to_s.downcase
   #     end
   #
   #     def self.load(value)
-  #       <work some magic>
+  #       value
   #     end
   #   end
+  #
+  # Properties of LowerCase type now will downcase it's values before
+  # it is persisted to the storage.
+  #
+  # One more real world example from dm-types library is a JSON type
+  # that stores values serialized as JSON, and often useful for embedded
+  # values:
+  #
+  #
+  # module DataMapper
+  #   module Types
+  #     class Json < DataMapper::Type
+  #       primitive String
+  #       length    65535
+  #       lazy      true
+  #
+  #       def self.load(value, property)
+  #         if value.nil?
+  #           nil
+  #         elsif value.kind_of?(String)
+  #           ::JSON.load(value)
+  #         else
+  #           raise ArgumentError, '+value+ of a property of JSON type must be nil or a String'
+  #         end
+  #       end
+  #
+  #       def self.dump(value, property)
+  #         if value.nil? || value.kind_of?(String)
+  #           value
+  #         else
+  #           ::JSON.dump(value)
+  #         end
+  #       end
+  #
+  #       def self.typecast(value, property)
+  #         if value.nil? || value.kind_of?(Array) || value.kind_of?(Hash)
+  #           value
+  #         else
+  #           ::JSON.load(value.to_s)
+  #         end
+  #       end
+  #     end # class Json
+  #     JSON = Json
+  #   end # module Types
+  # end # module DataMapper
   class Type
+
+    # Until cooperation of Property and Type does not change, each must
+    # have a separate list of options, because plugins (ex.: dm-validations)
+    # may want to extend one or the other, and expects no side effects
     PROPERTY_OPTIONS = [
       :accessor, :reader, :writer,
       :lazy, :default, :nullable, :key, :serial, :field, :size, :length,
-      :format, :index, :unique_index, :check, :ordinal, :auto_validation,
-      :validates, :unique, :track, :precision, :scale
+      :format, :index, :unique_index, :auto_validation,
+      :validates, :unique, :precision, :scale, :min, :max
     ]
 
-    PROPERTY_OPTION_ALIASES = {
-      :size => [ :length ]
-    }
-
     class << self
 
+      # TODO: document
+      # @api private
       def configure(primitive_type, options)
+        warn "DataMapper.Type.configure is deprecated, specify the primitive and options explicitly (#{caller[0]})"
+
         @_primitive_type = primitive_type
         @_options = options
 
         def self.inherited(base)
           base.primitive @_primitive_type
-
-          @_options.each do |k, v|
-            base.send(k, v)
-          end
+          @_options.each { |key, value| base.send(key, value) }
         end
 
         self
       end
 
-      # The Ruby primitive type to use as basis for this type. See
-      # DataMapper::Property::TYPES for list of types.
+      # Ruby primitive type to use as basis for this type. See
+      # Property::PRIMITIVES for list of types.
       #
-      # @param primitive<Class, nil>
+      # @param primitive [Class, nil]
       #   The class for the primitive. If nil is passed in, it returns the
       #   current primitive
       #
-      # @return <Class> if the <primitive> param is nil, return the current primitive.
+      # @return [Class] if the <primitive> param is nil, return the current primitive.
       #
       # @api public
       def primitive(primitive = nil)
         return @primitive if primitive.nil?
-
-        # TODO: change Integer to be used internally once most in-the-wild code
-        # is updated to use Integer for properties instead of Fixnum, or before
-        # DM 1.0, whichever comes first
-        if Fixnum == primitive
-          warn "#{primitive} properties are deprecated.  Please use Integer instead"
-          primitive = Integer
-        end
-
         @primitive = primitive
       end
 
-      # Load DataMapper::Property options
+      # Load Property options
       PROPERTY_OPTIONS.each do |property_option|
-        self.class_eval <<-EOS, __FILE__, __LINE__
-          def #{property_option}(arg = nil)
-            return @#{property_option} if arg.nil?
-
-            @#{property_option} = arg
-          end
-        EOS
-      end
-
-      # Create property aliases
-      PROPERTY_OPTION_ALIASES.each do |property_option, aliases|
-        aliases.each do |ali|
-          self.class_eval <<-EOS, __FILE__, __LINE__
-            alias #{ali} #{property_option}
-          EOS
-        end
+        self.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          def #{property_option}(*args)                                  # def unique(*args)
+            if args.any?                                                 #   if args.any?
+              @#{property_option} = args.first                           #     @unique = args.first
+            else                                                         #   else
+              defined?(@#{property_option}) ? @#{property_option} : nil  #     defined?(@unique) ? @unique : nil
+            end                                                          #   end
+          end                                                            # end
+        RUBY
       end
 
       # Gives all the options set on this type
       #
-      # @return <Hash> with all options and their values set on this type
+      # @return [Hash] with all options and their values set on this type
       #
       # @api public
       def options
@@ -123,10 +158,10 @@ module DataMapper
 
     # Stub instance method for dumping
     #
-    # @param value<Object, nil>       the value to dump
-    # @param property<Property, nil>  the property the type is being used by
+    # @param value     [Object, nil]    value to dump
+    # @param property  [Property, nil]  property the type is being used by
     #
-    # @return <Object> Dumped object
+    # @return [Object] Dumped object
     #
     # @api public
     def self.dump(value, property)
@@ -135,25 +170,28 @@ module DataMapper
 
     # Stub instance method for loading
     #
-    # @param value<Object, nil>       the value to serialize
-    # @param property<Property, nil>  the property the type is being used by
+    # @param value     [Object, nil]    value to serialize
+    # @param property  [Property, nil]  property the type is being used by
     #
-    # @return <Object> Serialized object. Must be the same type as the Ruby primitive
+    # @return [Object] Serialized object. Must be the same type as the Ruby primitive
     #
     # @api public
     def self.load(value, property)
       value
     end
 
+    # A hook to allow types to extend or modify property it's bound to.
+    # Implementations are not supposed to modify the state of the type class, and
+    # should produce no side-effects on the type class.
     def self.bind(property)
-      # This method should not modify the state of this type class, and
-      # should produce no side-effects on the type class. It's just a
-      # hook to allow your custom-type to modify the property it's bound to.
+      # no op
     end
 
   end # class Type
 
+  # @deprecated
   def self.Type(primitive_type, options = {})
+    warn "DataMapper.Type(#{primitive_type}) is deprecated, specify the primitive and options explicitly (#{caller[0]})"
     Class.new(Type).configure(primitive_type, options)
   end
 

data/lib/dm-core/types/boolean.rb

@@ -1,6 +1,6 @@
 module DataMapper
   module Types
-    class Boolean < DataMapper::Type
+    class Boolean < Type
       primitive TrueClass
     end # class Boolean
   end # module Types

data/lib/dm-core/types/discriminator.rb

@@ -1,33 +1,47 @@
 module DataMapper
   module Types
-    class Discriminator < DataMapper::Type
+    class Discriminator < Type
       primitive Class
-      track :set
-      default lambda { |r,p| p.model }
-      nullable false
+      default   lambda { |resource, property| resource.model }
+      nullable  false
 
+      # TODO: document
+      # @api private
       def self.bind(property)
-        model = property.model
+        repository_name = property.repository_name
+        model           = property.model
 
-        model.class_eval <<-EOS, __FILE__, __LINE__
-          def self.descendants
-            (@descendants ||= []).uniq!
-            @descendants
-          end
+        model.default_scope(repository_name).update(property.name => model.descendants)
 
-          after_class_method :inherited, :add_scope_for_discriminator
+        model.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          extend Chainable
 
-          def self.add_scope_for_discriminator(retval, target)
-            target.descendants << target
-            target.default_scope.update(#{property.name.inspect} => target.descendants)
-            propagate_descendants(target)
-          end
+          extendable do
+            def inherited(model)
+              super  # setup self.descendants
+              set_discriminator_scope_for(model)
+            end
+
+            def new(*args, &block)
+              if args.size == 1 && args.first.kind_of?(Hash)
+                discriminator = properties(repository_name).discriminator
+                model         = discriminator.typecast(args.first[discriminator.name])
+
+                if model.kind_of?(Model) && !model.equal?(self)
+                  return model.new(*args, &block)
+                end
+              end
+
+              super
+            end
+
+            private
 
-          def self.propagate_descendants(target)
-            descendants << target
-            superclass.propagate_descendants(target) if superclass.respond_to?(:propagate_descendants)
+            def set_discriminator_scope_for(model)
+              model.default_scope(#{repository_name.inspect}).update(#{property.name.inspect} => model.descendants)
+            end
           end
-        EOS
+        RUBY
       end
     end # class Discriminator
   end # module Types

data/lib/dm-core/types/object.rb

@@ -1,21 +1,24 @@
-require "base64"
-
 module DataMapper
   module Types
-    class Object < DataMapper::Type
+    class Object < Type
       primitive String
       size 65535
       lazy true
-      track :hash
 
+      # TODO: document
+      # @api private
       def self.typecast(value, property)
         value
       end
 
+      # TODO: document
+      # @api private
       def self.dump(value, property)
         Base64.encode64(Marshal.dump(value))
       end
 
+      # TODO: document
+      # @api private
       def self.load(value, property)
         value.nil? ? nil : Marshal.load(Base64.decode64(value))
       end

data/lib/dm-core/types/paranoid_boolean.rb

@@ -1,20 +1,22 @@
 module DataMapper
   module Types
-    class ParanoidBoolean < DataMapper::Type(Boolean)
+    class ParanoidBoolean < Type
       primitive TrueClass
       default   false
       lazy      true
 
+      # TODO: document
+      # @api private
       def self.bind(property)
-        model = property.model
-        repository = property.repository
+        repository_name = property.repository_name
+        model           = property.model
+        property_name   = property.name
 
-        model.send(:set_paranoid_property, property.name){true}
-
-        model.class_eval <<-EOS, __FILE__, __LINE__
+        model.send(:set_paranoid_property, property_name){true}
 
+        model.class_eval <<-RUBY, __FILE__, __LINE__ + 1
           def self.with_deleted
-            with_exclusive_scope(#{property.name.inspect} => true) do
+            with_exclusive_scope(#{property_name.inspect} => true) do
               yield
             end
           end
@@ -25,9 +27,9 @@ module DataMapper
             end
             save
           end
-        EOS
+        RUBY
 
-        model.default_scope(repository.name).update(property.name => false)
+        model.default_scope(repository_name).update(property_name => false)
       end
     end # class ParanoidBoolean
   end # module Types

data/lib/dm-core/types/paranoid_datetime.rb

@@ -1,19 +1,21 @@
 module DataMapper
   module Types
-    class ParanoidDateTime < DataMapper::Type(DateTime)
+    class ParanoidDateTime < Type
       primitive DateTime
       lazy      true
 
+      # TODO: document
+      # @api private
       def self.bind(property)
-        model = property.model
-        repository = property.repository
+        repository_name = property.repository_name
+        model           = property.model
+        property_name   = property.name
 
-        model.send(:set_paranoid_property, property.name){DateTime.now}
-
-        model.class_eval <<-EOS, __FILE__, __LINE__
+        model.send(:set_paranoid_property, property_name){DateTime.now}
 
+        model.class_eval <<-RUBY, __FILE__, __LINE__ + 1
           def self.with_deleted
-            with_exclusive_scope(#{property.name.inspect}.not => nil) do
+            with_exclusive_scope(#{property_name.inspect}.not => nil) do
               yield
             end
           end
@@ -24,9 +26,9 @@ module DataMapper
             end
             save
           end
-        EOS
+        RUBY
 
-        model.default_scope(repository.name).update(property.name => nil)
+        model.default_scope(repository_name).update(property_name => nil)
       end
     end # class ParanoidDateTime
   end # module Types

data/lib/dm-core/types/serial.rb

@@ -1,9 +1,9 @@
-# FIXME: can we alias this to the class Text if it isn't already defined?
 module DataMapper
   module Types
-    class Serial < DataMapper::Type
+    class Serial < Type
       primitive Integer
-      serial true
+      serial    true
+      min       1
     end # class Text
   end # module Types
 end # module DataMapper

data/lib/dm-core/types/text.rb

@@ -1,10 +1,9 @@
-# FIXME: can we alias this to the class Text if it isn't already defined?
 module DataMapper
   module Types
-    class Text < DataMapper::Type
+    class Text < Type
       primitive String
-      size 65535
-      lazy true
+      length    65535
+      lazy      true
     end # class Text
   end # module Types
 end # module DataMapper