simple_mapper 0.0.1

data/README.rdoc

@@ -0,0 +1,165 @@
+= SimpleMapper: A Non-Relational Object Mapper
+
+The simple data structures expressed through JSON are becoming more relevant every day.
+We use them to exchange information between services via Thrift, from server to HTTP
+client for RESTful services, or from server to HTTP client for Ajax-heavy web applications.
+
+While JSON structures map nicely to core Ruby objects (Hash, Array, etc.), those structures
+themselves do not provide business logic specific to an application's problem domain.
+Additionally, it is increasingly the case that the JSON object structure is the canonical
+representation your application receives for a given entity; a Thrift client, for instance,
+will send and receive JSON to the corresponding service.
+
+The object-relational mapper (ORM) traditionally addresses the need for business logic and
+domain-specific semantics at the application tier when working with a provider of structured
+data (i.e. a SQL-compliant relational database).  SimpleMapper attempts to provide something
+somewhat analogous to the ORM, but with JSON-based or "simple" data structures as the foundation
+for structuring data, rather than a relational model of classes/relations and their constraints,
+references, etc.
+
+= What?
+
+Say you need a service that serves and accepts JSON structures representing "users"
+(because, really, who doesn't need _that_ service?).  You might see data structures
+like this (in JSON):
+
+    {
+        id:            '348179ce-4d38-11df-8f4f-cd459e8422de',
+        registered_at: '2010-04-01 09:22:17-0400',
+        email:         'mister_hot_pantz@example.com',
+        title:         'Mr.',
+        first_name:    'Hot',
+        last_name:     'Pantz',
+        address:       {
+            address:  'One My Way',
+            address2: 'Not That Way',
+            city:     'New York',
+            state:    'NY',
+            postal:   '10010'
+        }
+    }
+
+That's not a particularly complex data structure, but let's note a few things:
+*    The +:id+ appears to be a GUID.  Fun.
+*    The +:registered_at+ is a timestamp with a particular format.  Also fun.
+*    There's an +:email+ address.  More fun.
+
+All of those things and their noted funness would benefit from business logic for validation
+purposes, encapsulation, etc.  Our OOPified brains long for these structures to map to
+an object.
+
+So, go ahead.
+
+    class User
+      # Get our attribute mapping magic
+      include SimpleMapper::Attributes
+      
+      # Define our typed attributes
+      maps :id,            :type => :simple_uuid, :default => :from_type
+      maps :registered_at, :type => :timestamp,   :default => :from_type
+
+      # Simple string attributes don't need a type
+      maps :email
+      maps :title
+      maps :first_name
+      maps :last_name
+
+      # nested attribute for the address.
+      maps :address do
+        # This block is evaluated in the context of new
+        # class that has the SimpleMapper behaviors
+        [:address, :address2, :city, :state, :postal].each {|attr| maps attr}
+
+        # How about a to_s that represents the full address as one string?
+        def to_s
+          "#{address}; #{address2}; #{city}, #{state} #{postal}"
+        end
+      end
+    end
+
+Now you have a class that describes the data structure you're working with.
+What now?
+
+You can create new objects and spit out the simple structure.
+
+    user = User.new(:email      => 'mister_hot_pantz@example.com',
+                    :title      => 'Mr.',
+                    :first_name => 'Hot',
+                    :last_name  => 'Pantz',
+                    :address    => {:address  => 'One My Way',
+                                    :address2 => 'Not That Way',
+                                    :city     => 'New York',
+                                    :state    => 'NY',
+                                    :postal   => '10010'})
+    # the :simple_uuid type gives GUIDs, with a :default of :from_type
+    # meaning it'll autopopulate
+    # This prints some GUID like '348179ce-4d38-11df-8f4f-cd459e8422de':
+    puts user.id
+
+    # And the :default of :from_type on a :timestamp type gets the current date/time.
+    # This will print 'DateTime'
+    puts user.registered_at.class
+    # This will print it using DateTime's default :to_s format
+    # like '2010-0421T07:41:46-04:00'
+    puts user.registered_at
+
+    # This will print out 'One My Way; Not That Way; New York, NY 10010':
+    puts user.address
+
+    # The :to_simple method dumps the structure out in simple object format,
+    # which is readily JSON-ifiable.  However, it'll enforce defaults and type
+    # formatting and such, so that things like timestamps will be stringified with
+    # the correct format.
+    user.to_simple
+
+    # Results in a structure like:
+    {
+        :id            => '348179ce-4d38-11df-8f4f-cd459e8422de',
+        :registered_at => '2010-04-21 07:41:46-04:00',
+        :email         => 'mister_hot_pantz@example.com',
+        :title         => 'Mr.',
+        :first_name    => 'Hot',
+        :last_name     => 'Pantz',
+        :address       => {
+            :address  => 'One My Way',
+            :address2 => 'Not That Way',
+            :city     => 'New York',
+            :state    => 'NY',
+            :postal   => '10010',
+        },
+    }
+
+So, the +:new+ constructor and the +:to_simple+ method give you input and output
+from/to simple structures, while the +SimpleMapper::Attributes+ module gives you
+semantics for defining higher-level classes on top of those simple structures.
+
+What if my service needs to have something analogous to an update, such that I only
+get the simple structure for attributes that were changed?
+
+    user.last_name = 'Pantalonez'
+    user.to_simple(:changed => true)
+    # Results in:
+    # { :last_name => 'Pantalonez' }
+
+The +:changed+ option indicates that we only want attributes that were altered since
+the instance was instantiated.  It doesn't care if the values actually differ from the
+original, it only cares if the attribute was assigned since creation.
+
+Similarly, you can provide a +:defined+ option to the +:to_simple+ invocation, and
+you'll only get attributes in the resulting structure that have a non-nil value.
+This is useful if you're ultimately dealing with a data source that manages such
+things itself (like allowing +NULL+ on a particular database column) or is sparse
+and would thus prefer to not have any entry for an undefined value at all (like
+Cassandra, MongoDB, etc.)
+
+= What's Coming
+
+SimpleMapper is young as of this writing.  There's a basic type system with
+defaults.  Support for nested structures is pretty simple, as shown above.
+
+Features expected in the near future include:
+* collections: deal with an attribute that is a collection
+* pattern-based collections: group all key/value pairs into a single collection attribute
+  for any keys that match a developer-specific pattern
+* ActiveModel compliance to allow validation, callbacks, etc.
+

data/Rakefile.rb

@@ -0,0 +1,11 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/clean'
+
+CLOBBER.include('*.gem')
+
+Rake::TestTask.new do |t|
+  t.pattern = 'test/**/*_test.rb'
+  t.libs = ['test', 'lib']
+end
+

data/lib/simple_mapper.rb

@@ -0,0 +1,8 @@
+module SimpleMapper
+  require 'simple_mapper/change_hash'
+  require 'simple_mapper/collection'
+  require 'simple_mapper/attribute'
+  require 'simple_mapper/attribute/collection'
+  require 'simple_mapper/attribute/pattern'
+  require 'simple_mapper/attributes'
+end

data/lib/simple_mapper/attribute.rb

@@ -0,0 +1,119 @@
+module SimpleMapper
+  class Attribute
+    Options = [
+      :default,
+      :key,
+      :type,
+      :mapper,
+    ]
+    attr_accessor :key, :name, :default, :mapper
+
+    def type=(new_type)
+      @type = new_type
+    end
+
+    def type
+      @type || mapper
+    end
+
+    def initialize(name, options = {})
+      self.key = self.name = name
+      process_options(options)
+    end
+
+    def process_options(options = {})
+      Options.each do |option|
+        self.send(:"#{option.to_s}=", options[option]) if options[option]
+      end
+    end
+
+    def source_value(object)
+      source = object.simple_mapper_source
+      source.has_key?(key) ? source[key] : source[key.to_s]
+    end
+
+    def transformed_source_value(object)
+      val = source_value(object)
+      val = default_value(object) if val.nil?
+      if type = self.type
+        if type.respond_to?(:decode)
+          type.decode(val)
+        else
+          type = SimpleMapper::Attributes.type_for(type)
+          if expected = type[:expected_type] and val.instance_of? expected
+            val
+          else
+            type[:converter].decode(val)
+          end
+        end
+      else
+        val
+      end
+    end
+
+    def value(object)
+      object.send(name)
+    end
+
+    def converter
+      return nil unless type
+      converter = type.respond_to?(:encode) || type.respond_to?(:decode) ? type : (t = SimpleMapper::Attributes.type_for(type) and t[:converter])
+      raise SimpleMapper::InvalidTypeException unless converter
+      converter
+    end
+
+    def encode(value)
+      return value unless c = converter
+      c.encode(value)
+    end
+
+    def to_simple(object, container, options = {})
+      raw_value = self.value(object)
+      if mapper
+        value = raw_value.nil? ? nil : raw_value.to_simple(options)
+      else
+        value = encode(raw_value)
+      end
+      container[options[:string_keys] ? key.to_s : key] = value unless value.nil? and options[:defined]
+    end
+
+    def change_tracking_for(object)
+      object.simple_mapper_changes
+    end
+
+    def changed!(object, flag=true)
+      if flag
+        change_tracking_for(object)[name] = true
+      else
+        change_tracking_for(object).delete(name)
+        false
+      end
+    end
+
+    def changed?(object)
+      if mapper and val = value(object)
+        val.changed?
+      else
+        (change_tracking_for(object)[name] && true) || false
+      end
+    end
+
+    def default_value(object)
+      case d = self.default
+        when :from_type
+          converter.default
+        when Symbol
+          object.send(d)
+        else
+          nil
+      end
+    end
+
+    def freeze_for(object)
+      if mapper and val = value(object)
+        val.freeze
+      end
+    end
+  end
+
+end

data/lib/simple_mapper/attribute/collection.rb

@@ -0,0 +1,130 @@
+# Include in a SimpleMapper::Attribute to give it collection behaviors:
+#  * have an attribute be a collection (i.e. a hash or array) of values
+#    rather than a single value
+#  * map N keys from a source value to the attribute, based on the +:member_key?+ test
+#  * map keys/values from the collection object back to a "source" structure
+module SimpleMapper::Attribute::Collection
+  # Given an _object_ that has the attribute represented by the receiver,
+  # returns the source value for the attribute after applying defaults and types.
+  # The type check is applied to either the raw source value (if one exists) or
+  # the default value (if no source exists and a default was specified for the attribute).
+  #
+  # Type checking is not enforced here; it is expected that +:source_value+,
+  # +:default_value+, and +:apply_type+ will all return objects of the expected collection
+  # type (or consistent interface).
+  def transformed_source_value(object)
+    val = source_value(object)
+    val = default_value(object) if val.nil?
+    val = apply_type(val) if type
+    val.change_tracking = true if val.respond_to?(:change_tracking)
+    val
+  end
+
+  def member_key?(key)
+    false
+  end
+
+  def source_value(object)
+    object.simple_mapper_source.inject(new_collection) do |hash, keyval|
+      hash[from_simple_key(keyval[0])] = keyval[1] if member_key?(keyval[0])
+      hash
+    end
+  end
+
+  # If the receiver has a valid type specified, returns a new collection based on
+  # _value_, with the key/value pairs from _value_ but each value encoded by
+  # the type converter.
+  def apply_type(value)
+    converter = self.converter
+    value.inject(new_collection) do |hash, keyval|
+      hash[keyval[0]] = converter.decode(keyval[1])
+      hash
+    end
+  end
+
+  # Returns a new collection object to be used as the basis for building the attribute's
+  # value collection; by default, returns instances of SimpleMapper::Collection::Hash.
+  # Override this to alter the kinds of collections your attributes work with.
+  def new_collection
+    h = SimpleMapper::Collection::Hash.new
+    h.attribute = self
+    h
+  end
+
+  # Given a _key_ from the source structure (the "simple structure"), returns a
+  # transformed key as it will be entered in the attribute's collection value.
+  # By default, this simply passes through _key_, but it can be overridden to
+  # allow for more sophisticated source/object mappings.
+  def from_simple_key(key)
+    key
+  end
+
+  # The reverse of +:to_simple_key+, given a _key_ from the attribute collection,
+  # returns the transformed version of that key as it should appear in the "simple"
+  # representation of the object.
+  def to_simple_key(key)
+    key
+  end
+
+  def freeze_for(object)
+    val = value(object)
+    if val
+      if mapper
+        if val.respond_to?(:values)
+          val.values.each {|member| member.freeze}
+        else
+          val.each {|member| member.freeze}
+        end
+      end
+      val.freeze
+    end
+  end
+
+  def changed?(object)
+    val = value(object)
+    return true if val.changed_members.size > 0
+    return true if mapper and val.find {|keyval| keyval[1].changed?}
+    false
+  end
+
+  # Converts the _object_'s attribute value into its simple representation,
+  # putting the keys/values into _container_.  This is conceptually consistent
+  # with +SimpleMapper::Attributes#to_simple+, but adds a few collection-oriented
+  # concerns:
+  #  * the attribute's value is assumed to be a collection with N key/value pairs
+  #    to be mapped into _container_
+  #  * the keys are transformed via +:to_simple_key+ on their way into _container_.
+  #
+  # This will work with any kind of _container_ that can be assigned to via +[]=+,
+  # and any value for the attribute that supports +:inject+ in the same manner as
+  # a Hash (yields the accumulated value and a key/value pair to the block).
+  def to_simple(object, container, options = {})
+    val = value(object)
+    mapper = self.mapper
+    strings = options[:string_keys] || false
+    changed_members = change_tracking_for(val)
+    if options[:changed]
+      if mapper
+        change_proc = Proc.new do |key, val|
+          changed_members[key] or (! val.nil? and val.changed?)
+        end
+      else
+        change_proc = Proc.new {|k, v| changed_members[k]}
+      end
+    else
+      change_proc = nil
+    end
+    changes = options[:changed] || false
+    container = val.inject(container) do |hash, keyvalue|
+      key = to_simple_key(keyvalue[0])
+      hash[strings ? key.to_s : key] = mapper ? keyvalue[1].to_simple(options) : encode(keyvalue[1]) if ! change_proc or change_proc.call(*keyvalue)
+      hash
+    end
+    if (change_proc or options[:all]) and ! options[:defined]
+      changed_members.keys.find_all {|x| ! val.is_member?(x)}.each do |key|
+        container[to_simple_key(key)] = nil
+      end
+    end
+    container
+  end
+end

data/lib/simple_mapper/attribute/pattern.rb

@@ -0,0 +1,19 @@
+class SimpleMapper::Attribute::Pattern < SimpleMapper::Attribute
+  include SimpleMapper::Attribute::Collection
+
+  attr_reader :pattern
+
+  def initialize(name, options = {})
+    super(name, options)
+    self.pattern = options[:pattern]
+  end
+
+  def pattern=(value)
+    raise SimpleMapper::InvalidPatternException unless value.respond_to?(:match)
+    @pattern = value
+  end
+
+  def member_key?(key)
+    (pattern.match(key.to_s) and true) or false
+  end
+end