simple_mapper 0.0.1

data/lib/simple_mapper/attributes.rb

@@ -0,0 +1,196 @@
+module SimpleMapper
+  module Attributes
+    self.instance_eval do
+      def types
+        @types ||= {}
+      end
+
+      def type_for(name)
+        types[name]
+      end
+
+      def register_type(name, expected_type, converter)
+        types[name] = {:name => name, :expected_type => expected_type, :converter => converter}
+      end
+    end
+
+    def self.included(klass)
+      klass.extend ClassMethods
+    end
+
+    module ClassMethods
+      def simple_mapper
+        @simple_mapper ||= SimpleMapper::Attributes::Manager.new(self)
+      end
+
+      def maps(attr, *args, &block)
+        if block_given?
+          hash = args.last
+          args << (hash = {}) unless hash.instance_of? Hash
+          mapper = simple_mapper.create_anonymous_mapper(&block)
+          hash[:type] ||= mapper
+          hash[:mapper] = mapper
+        end
+        attribute = simple_mapper.create_attribute(attr, *args)
+        simple_mapper.install_attribute attr, attribute
+      end
+    end
+
+    def attribute_object_for(attr)
+      self.class.simple_mapper.attributes[attr]
+    end
+
+    def key_for(attr)
+      attribute_object_for(attr).key
+    end
+
+    def reset_attribute(attr)
+      @simple_mapper_init.delete attr
+      attribute_changed!(attr, false)
+      remove_instance_variable(:"@#{attr}")
+    end
+
+    def write_attribute(attr, value)
+      raise(RuntimeError, "can't modify frozen object") if frozen?
+      instance_variable_set(:"@#{attr}", value)
+      @simple_mapper_init[attr] = true
+      attribute_changed! attr
+      value
+    end
+
+    def transform_source_attribute(attr)
+      attribute_object_for(attr).transformed_source_value(self)
+    end
+
+    def read_source_attribute(attr)
+      attribute_object_for(attr).source_value(self)
+    end
+
+    def read_attribute(attr)
+      if @simple_mapper_init[attr]
+        instance_variable_get(:"@#{attr}")
+      else
+        result = instance_variable_set(:"@#{attr}", transform_source_attribute(attr))
+        @simple_mapper_init[attr] = true
+        result
+      end
+    end
+
+    def get_attribute_default(attr)
+      attribute_object_for(attr).default_value(self)
+    end
+
+    def simple_mapper_changes
+      @simple_mapper_changes ||= SimpleMapper::ChangeHash.new
+    end
+
+    def attribute_changed!(attr, flag=true)
+      attribute_object_for(attr).changed!(self, flag)
+    end
+
+    def attribute_changed?(attr)
+      attribute_object_for(attr).changed?(self)
+    end
+
+    def all_changed!
+      simple_mapper_changes.all_changed!
+    end
+
+    def all_changed?
+      simple_mapper_changes.all
+    end
+
+    def changed_attributes
+      attribs = self.class.simple_mapper.attributes
+      if simple_mapper_changes.all
+        attribs.keys
+      else
+        attribs.inject([]) do |list, keyval|
+          list << keyval[0] if keyval[1].changed?(self)
+          list
+        end
+      end
+    end
+
+    def changed?
+      changed_attributes.size > 0
+    end
+
+    def freeze
+      self.class.simple_mapper.attributes.values.each {|attribute| attribute.freeze_for(self)}
+      simple_mapper_changes.freeze
+    end
+
+    def frozen?
+      simple_mapper_changes.frozen?
+    end
+
+    attr_reader :simple_mapper_source
+
+    def initialize(values = {})
+      @simple_mapper_source = values
+      @simple_mapper_init = {}
+      @simple_mapper_changes = SimpleMapper::ChangeHash.new
+    end
+
+    def to_simple(options = {})
+      clean_opt = options.clone
+      # if all_changed? true, we disregard changed flag entirely, so the entire graph
+      # appears to be changed in result set.  We
+      # also propagate the :all flag, which tells
+      # objects that support it to include information
+      # about members that were removed.
+      if all_changed?
+        clean_opt.delete(:changed)
+        clean_opt[:all] = true
+      end
+      changes = (clean_opt[:changed] && true) || false
+      self.class.simple_mapper.attributes.values.inject({}) do |container, attrib|
+        attrib.to_simple(self, container, clean_opt) if !changes or attrib.changed?(self)
+        container
+      end
+    end
+
+    class Manager
+      attr_accessor :applies_to
+
+      def initialize(apply_to = nil)
+        self.applies_to = apply_to if apply_to
+      end
+
+      def attributes
+        @attributes ||= {}
+      end
+
+      def create_attribute(name, options = {})
+        attrib_class = options[:attribute_class] || SimpleMapper::Attribute
+        attrib_class.new(name, options)
+      end
+
+      def install_attribute(attr, object)
+        read_body = Proc.new { read_attribute(attr) }
+        write_body = Proc.new {|value| write_attribute(attr, value)}
+        applies_to.module_eval do
+          define_method(attr, &read_body)
+          define_method(:"#{attr}=", &write_body)
+        end
+        attributes[attr] = object
+      end
+
+      def create_anonymous_mapper(&block)
+        mapper = Class.new do
+          include SimpleMapper::Attributes
+          def self.decode(*arg)
+            new(*arg)
+          end
+        end
+        mapper.module_eval &block if block_given?
+        mapper
+      end
+    end
+  end
+end
+
+require 'simple_mapper/exceptions'
+require 'simple_mapper/attributes/types'
+

data/lib/simple_mapper/attributes/types.rb

@@ -0,0 +1,224 @@
+module SimpleMapper::Attributes::Types
+  # Provides basic support for floating point numbers, closely tied to
+  # the core Ruby :Float:.
+  #
+  # Registered as type <tt>:float</tt>
+  #
+  # This is intended to be reasonably flexible and work with inputs
+  # that look numeric whether or not they literally appear to be "floats".
+  module Float
+    PATTERN = /^([0-9]+)(?:(\.)([0-9]*))?$/
+
+    # Decode a numeric-looking +value+ (whether a string or otherwise) into
+    # a +Float+.
+    #
+    # String inputs for +value+ should be numeric and may or may not have
+    # a decimal point, with or without digits following the decimal point.
+    # Therefore, the following values would all decode nicely:
+    #  * +"14"+ to +14.0+
+    #  * +"0"+ to +0.0+
+    #  * +"123."+ to +123.0+
+    #  * +"100.22022"+ to +100.22022+
+    #  * +"0.0001"+ to +0.0001+
+    #  * +14+ to +14.0+
+    #  * +0+ to +0.0+
+    #
+    # The empty string will result in a value of +nil+
+    def self.decode(value)
+      return nil if (str = value.to_s).length == 0
+      return value if Float === value
+      match = str.match(PATTERN)
+      raise(SimpleMapper::TypeConversionException, "Cannot decode '#{value}' to Float.") unless match
+      value = match[1]
+      value += match[2] + match[3] if match[3].to_s.length > 0
+      value.to_s.to_f
+    end
+
+    # Encodes a float-like +value+ as a string, conforming to the basic
+    # syntax used for +decode+.
+    def self.encode(value)
+      return nil if value.nil?
+      if ! value.respond_to?(:to_f) or value.respond_to?(:match) && ! value.match(PATTERN)
+        raise(SimpleMapper::TypeConversionException, "Cannot encode '#{value}' as Float.")
+      end
+      value.to_f.to_s
+    end
+
+    # Returns the type default value of +nil+.
+    def self.default
+      nil
+    end
+  end
+  SimpleMapper::Attributes.register_type(:float, ::Float, Float)
+
+  # Provides simple string type support.
+  #
+  # Registered as <tt>:string</tt>.
+  #
+  # This is intended to be quite flexible and rely purely on duck typing.
+  # It should work with any input that supports <tt>:to_s</tt>, and is
+  # not strictly limited to actual +String+ instances.
+  module String
+    # Decodes +value+ into a +String+ object via the <tt>:to_s</tt> of
+    # +value+.  Passes nils through unchanged.  For the majority use case,
+    # most of the time the result and the input will be equal.
+    def self.decode(value)
+      return nil if value.nil?
+      value.to_s
+    end
+
+    # Encodes +value+ as a string via its <tt>:to_s</tt> method.  Passes nils
+    # through unchanged.
+    def self.encode(value)
+      return nil if value.nil?
+      value.to_s
+    end
+
+    # Returns the empty string for a "default".
+    def self.default
+      ''
+    end
+  end
+  SimpleMapper::Attributes.register_type(:string, ::String, String)
+
+  # Provides basic UUID type support derived from the +simple_uuid+ gem.
+  #
+  # Passes nils through unchanged, but otherwise expects to work with
+  # instances of <tt>SimpleUUID::UUID</tt> or GUID strings.  Attributes
+  # using this type will store the data simply as a GUID-conforming string
+  # as implemented by +SimpleUUID::UUID#to_guid+.  For both decoding and
+  # encoding, a GUID string or an actual +SimpleUUID::UUID+ instance may
+  # be provided, but the result is always the corresponding GUID string.
+  #
+  # Registered as <tt>:simple_uuid</tt>.
+  module SimpleUUID
+    require 'simple_uuid'
+    EXPECTED_CLASS = ::SimpleUUID::UUID
+
+    # Encoded a <tt>SimpleUUID::UUID</tt> instance, or a GUID string,
+    # as a GUID string.  GUID strings for +value+ will be validated by
+    # +SimpleUUID::UUID+ prior to passing through as the result.
+    #
+    # Passes nils through unchanged.
+    def self.encode(value)
+      normalize(value)
+    end
+
+    # Decode a <tt>SimpleUUID::UUID</tt> instance or GUID string into
+    # validated GUID string; strings will be validated by +SimpleUUID::UUID+
+    # prior to passing through as the result.
+    #
+    # Passes nils through unchanged.
+    def self.decode(value)
+      normalize(value)
+    end
+
+    def self.normalize(value)
+      value.nil? ? nil : EXPECTED_CLASS.new(value).to_guid
+    end
+
+    # Returns a new GUID string value.
+    def self.default
+      EXPECTED_CLASS.new.to_guid
+    end
+  end
+  SimpleMapper::Attributes.register_type(:simple_uuid, nil, SimpleUUID)
+
+  # Provides timezone-aware second-resolution timestamp support for
+  # basic attributes.
+  #
+  # Attributes of this type will have values that are instances of +DateTime+.
+  # These +DateTime+ values will be reduced to strings of format +'%Y-%m-%d %H:%M:%S%z'+
+  # when converting to a simple structure.
+  #
+  # On input, a +DateTime+ instance or a string matching the above format will be
+  # accepted and map to the proper +DateTime+.
+  #
+  # Decoding or encoding nils will simply pass nil through.
+  #
+  # Registered as type +:timestamp+
+  module Timestamp
+    require 'date'
+
+    FORMAT = '%Y-%m-%d %H:%M:%S%z'
+
+    # Encode a +DateTime+ _value_ as a string of format +'%Y-%m-%d %H:%M:%S%z'+.
+    # Given +nil+ for _value, +nil+ will be returned.
+    def self.encode(value)
+     return nil if value.nil?
+     value.strftime FORMAT
+    end
+
+    # Decode a _value_ string of format +'%Y-%m-%d %H:%M:%S%z' into a +DateTime+ instance.
+    # If given a +DateTime+ instance for _value_, that instance will be returned.
+    # Given +nil+ for _value_, +nil+ will be returned.
+    def self.decode(value)
+      return nil if value.nil?
+      return value if value.instance_of? DateTime
+      DateTime.strptime(value, FORMAT)
+    end
+
+    # Return a new +DateTime+ instance representing the current time.  Note that this
+    # will include fractional seconds; this precision is lost when encoded to string,
+    # as the string representation only has a precision to the second.
+    def self.default
+      DateTime.now
+    end
+  end
+  SimpleMapper::Attributes.register_type(:timestamp, DateTime, Timestamp)
+
+  module Integer
+    def self.convert(value)
+      converted = value.to_i
+      unless value == converted or value.to_s == converted.to_s or converted.to_f.to_s == value.to_s
+        raise SimpleMapper::TypeConversionException, "cannot convert #{value} to Integer"
+      end
+      converted
+    end
+
+    # raise a TypeConversionException if not a valid Integer
+    # otherwise, convert to a string
+    def self.encode(value)
+      convert(value).to_s
+    end
+
+    def self.decode(value)
+      convert(value)
+    end
+  end
+  SimpleMapper::Attributes.register_type(:integer, ::Integer, Integer)
+
+  module TimestampHighRes
+    require 'bigdecimal'
+    unless BigDecimal.method_defined?(:to_r)
+      require 'bigdecimal/util'
+    end
+
+    SECOND_FRACTION = Rational(1, 24 * 60 * 60)
+    PATTERN = /^([^.]+)\.(\d+)([-+]\d{4})$/
+    OUT_FORMAT = '%Y-%m-%d %H:%M:%S.%N%z'
+    IN_FORMAT  = '%Y-%m-%d %H:%M:%S%z'
+
+    def self.encode(value)
+      return nil if value.nil?
+      value.strftime(OUT_FORMAT)
+    end
+
+    def self.decode(value)
+      if value.kind_of?(DateTime)
+        value
+      elsif value.nil?
+        nil
+      else
+        if match = PATTERN.match(value.to_s)
+          stamp, second_fraction, zone = match.captures
+          subseconds = BigDecimal('0.' + second_fraction).to_r
+          DateTime.strptime(stamp + zone, IN_FORMAT) + (subseconds * SECOND_FRACTION)
+        else
+          raise SimpleMapper::TypeConversionException, "cannot transform '#{value}' into hi-res DateTime"
+        end
+      end
+    end
+  end
+  SimpleMapper::Attributes.register_type(:timestamp_high_res, ::DateTime, TimestampHighRes)
+end

data/lib/simple_mapper/change_hash.rb

@@ -0,0 +1,14 @@
+module SimpleMapper
+  class ChangeHash < Hash
+    attr_reader :all
+
+    def all_changed!
+      @all = true
+    end
+
+    def clear
+      @all = false
+      super
+    end
+  end
+end

data/lib/simple_mapper/collection.rb

@@ -0,0 +1,169 @@
+require 'delegate'
+module SimpleMapper
+  module Collection
+    module CommonMethods
+      attr_accessor :attribute
+      attr_accessor :change_tracking
+
+      def simple_mapper_changes
+        @simple_mapper_changes ||= SimpleMapper::ChangeHash.new
+      end
+
+      def changed_members
+        simple_mapper_changes.keys
+      end
+
+      def member_changed!(key, value)
+        return nil unless change_tracking
+        # If the key is new to the collection, we're fine.
+        # If the key is already in the collection, then we have to consider
+        # whether or not value is itself a mapper.  If it is, we want it to consider
+        # all of its attributes changed, since they are all replacing whatever was
+        # previously associated with +key+ in the collection.
+        if ! value.nil? and value.respond_to?(:all_changed!)
+          value.all_changed!
+        end
+        simple_mapper_changes[key] = true
+      end
+
+      # Predicate that returns +true+ if _key_ is present in the collection.
+      # Returns +nil+ by default; this must be implemented appropriately per
+      # class that uses this module.
+      def is_member?(key)
+        nil
+      end
+
+      def []=(key, value)
+        member_changed!(key, value)
+        super(key, value)
+      end
+
+      def build(*args)
+        attribute.mapper.new(*args)
+      end
+    end
+
+    class Hash < DelegateClass(::Hash)
+      include CommonMethods
+
+      def is_member?(key)
+        key? key
+      end
+
+      def initialize(hash = {})
+        super(hash)
+      end
+
+      def delete(key)
+        member_changed!(key, nil)
+        super(key)
+      end
+
+      def reject!
+        changed = false
+        each do |key, val|
+          if yield(key, val)
+            changed = true
+            delete(key)
+          end
+        end
+        changed ? self : nil
+      end
+
+      def delete_if
+        reject! {|k, v| yield(k, v)}
+        self
+      end
+    end
+
+    class Array < DelegateClass(::Array)
+      include CommonMethods
+
+      def initialize(array=[])
+        super(array)
+      end
+
+      def is_member?(key)
+        key = key.to_i
+        key >= 0 and key < size
+      end
+
+      def keys
+        (0..size - 1).to_a
+      end
+
+      def inject(*args)
+        (0..size - 1).inject(*args) {|accum, key| yield(accum, [key, self[key]])}
+      end
+
+      def <<(value)
+        member_changed!(size, value)
+        super(value)
+      end
+
+      def push(*values)
+        values.each {|val| self << val }
+        self
+      end
+
+      def slice!(start_or_range, length=1)
+        result = nil
+        original_size = size
+        case start_or_range
+          when Range
+            result = super(start_or_range)
+            if result
+              change_min = start_or_range.min
+            end
+          else
+            result = super(start_or_range, length)
+            if result
+              change_min = start_or_range < 0 ? original_size + start_or_range : start_or_range
+            end
+        end
+        if result
+          change_min = 0 if change_min < 0
+          (change_min..original_size - 1).each {|index| member_changed!(index, self[index]) }
+        end
+        result
+      end
+
+      alias_method :_delete, :delete_at
+      private :_delete
+
+      def delete_at(index)
+        original_size = size
+        result = _delete(index)
+        if size != original_size
+          (index..original_size - 1).each {|idx| member_changed!(idx, self[idx])}
+        end
+        result
+      end
+
+      def reject!
+        first = nil
+        last = size - 1
+        index = 0
+        while index < size
+          if yield(self[index])
+            first ||= index
+            _delete(index)
+          else
+            index += 1
+          end
+        end
+        if first
+          (first..last).each {|idx| member_changed!(idx, self[idx])}
+          self
+        else
+          nil 
+        end
+      end
+
+      def delete_if
+        reject! {|x| yield(x)}
+        self
+      end
+    end
+  end
+end