cartograph 1.0.0

data/lib/cartograph.rb

@@ -0,0 +1,24 @@
+require "cartograph/version"
+require 'json'
+
+module Cartograph
+  autoload :DSL, 'cartograph/dsl'
+  autoload :Map, 'cartograph/map'
+  autoload :Property, 'cartograph/property'
+  autoload :PropertyCollection, 'cartograph/property_collection'
+  autoload :RootKey, 'cartograph/root_key'
+  autoload :ScopeProxy, 'cartograph/scope_proxy'
+
+  autoload :Artist, 'cartograph/artist'
+  autoload :Sculptor, 'cartograph/sculptor'
+
+  class << self
+    attr_accessor :default_dumper
+    attr_accessor :default_loader
+    attr_accessor :default_cache
+    attr_accessor :default_cache_key
+  end
+
+  self.default_dumper = JSON
+  self.default_loader = JSON
+end

data/lib/cartograph/artist.rb

@@ -0,0 +1,34 @@
+module Cartograph
+  class Artist
+    attr_reader :object, :map
+
+    def initialize(object, map)
+      @object = object
+      @map = map
+    end
+
+    def properties
+      map.properties
+    end
+
+    def draw(scope = nil)
+      if map.cache
+        cache_key = map.cache_key.call(object, scope)
+        map.cache.fetch(cache_key) { build_properties(scope) }
+      else
+        build_properties(scope)
+      end
+    end
+
+    def build_properties(scope)
+      scoped_properties = scope ? properties.filter_by_scope(scope) : properties
+      scoped_properties.each_with_object({}) do |property, mapped|
+        begin
+          mapped[property.key] = property.value_for(object, scope)
+        rescue NoMethodError => e
+          raise ArgumentError, "#{object} does not respond to #{property.name}, so we can't map it"
+        end
+      end
+    end
+  end
+end

data/lib/cartograph/dsl.rb

@@ -0,0 +1,104 @@
+module Cartograph
+  module DSL
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      def cartograph(&block)
+        @cartograph_map ||= Map.new
+
+        if block_given?
+          block.arity > 0 ? block.call(@cartograph_map) : @cartograph_map.instance_eval(&block)
+        end
+
+        @cartograph_map
+      end
+
+      # Returns a hash representation of the object based on the mapping
+      #
+      # @param scope [Symbol] the scope of the mapping
+      # @param object the object to be mapped
+      # @return [Hash, Array]
+      def hash_for(scope, object)
+        drawn_object = Artist.new(object, @cartograph_map).draw(scope)
+        prepend_root_key(scope, :singular, drawn_object)
+      end
+
+      # Returns a hash representation of the collection of objects based on the mapping
+      #
+      # @param scope [Symbol] the scope of the mapping
+      # @params objects [Array] the array of objects to be mapped
+      # @return [Hash, Array]
+      def hash_collection_for(scope, objects)
+        drawn_objects = objects.map do |object|
+          Artist.new(object, @cartograph_map).draw(scope)
+        end
+
+        prepend_root_key(scope, :plural, drawn_objects)
+      end
+
+      def representation_for(scope, object, dumper = Cartograph.default_dumper)
+        dumper.dump(hash_for(scope, object))
+      end
+
+      def represent_collection_for(scope, objects, dumper = Cartograph.default_dumper)
+        dumper.dump(hash_collection_for(scope, objects))
+      end
+
+      def extract_single(content, scope, loader = Cartograph.default_loader)
+        loaded = loader.load(content)
+
+        retrieve_root_key(scope, :singular) do |root_key|
+          # Reassign loaded if a root key exists
+          loaded = loaded[root_key]
+        end
+
+        Sculptor.new(loaded, @cartograph_map).sculpt(scope)
+      end
+
+      def extract_into_object(object, content, scope, loader = Cartograph.default_loader)
+        loaded = loader.load(content)
+
+        retrieve_root_key(scope, :singular) do |root_key|
+          # Reassign loaded if a root key exists
+          loaded = loaded[root_key]
+        end
+
+        sculptor = Sculptor.new(loaded, @cartograph_map)
+        sculptor.sculpted_object = object
+        sculptor.sculpt(scope)
+      end
+
+      def extract_collection(content, scope, loader = Cartograph.default_loader)
+        loaded = loader.load(content)
+
+        retrieve_root_key(scope, :plural) do |root_key|
+          # Reassign loaded if a root key exists
+          loaded = loaded[root_key]
+        end
+
+        loaded.map do |object|
+          Sculptor.new(object, @cartograph_map).sculpt(scope)
+        end
+      end
+
+      private
+      def prepend_root_key(scope, plurality, payload)
+        retrieve_root_key(scope, plurality) do |root_key|
+          # Reassign drawed if a root key exists
+          payload = { root_key => payload }
+        end
+
+        payload
+      end
+
+      def retrieve_root_key(scope, type, &block)
+        if root_key = @cartograph_map.root_key_for(scope, type)
+          yield root_key
+        end
+      end
+
+    end
+  end
+end

data/lib/cartograph/map.rb

@@ -0,0 +1,91 @@
+require 'thread'
+
+module Cartograph
+  class Map
+    def initialize
+      @scope_mutex = Mutex.new
+    end
+
+    def property(*args, &block)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+
+      # Append scopes if we're currently mapping in a scoped block
+      options[:scopes] ||= []
+      options[:scopes] += Array(@current_scopes)
+
+      args.each do |prop|
+        properties << Property.new(prop, options, &block)
+      end
+    end
+
+    def properties
+      @properties ||= PropertyCollection.new
+    end
+
+    def scoped(*scopes, &block)
+      @scope_mutex.synchronize do
+        @current_scopes = scopes
+
+        instance_eval(&block) if block_given?
+
+        @current_scopes = nil
+      end
+    end
+
+    def root_keys
+      @root_keys ||= []
+    end
+
+    def mapping(klass = nil)
+      @mapping = klass if klass
+      @mapping
+    end
+
+    def root_key(options)
+      root_keys << RootKey.new(options)
+    end
+
+    def cache(object = nil)
+      @cache = object unless object.nil?
+      @cache.nil? ? Cartograph.default_cache : @cache
+    end
+
+    def cache_key(&calculator)
+      @cache_calculator = calculator if block_given?
+      @cache_calculator.nil? ? Cartograph.default_cache_key : @cache_calculator
+    end
+
+    def root_key_for(scope, type)
+      return unless %i(singular plural).include?(type)
+
+      if (root_key = root_keys.select {|rk| rk.scopes.include?(scope) }[0])
+        root_key.send(type)
+      end
+    end
+
+    def dup
+      Cartograph::Map.new.tap do |map|
+        self.properties.each do |property|
+          map.properties << property.dup
+        end
+
+        map.mapping self.mapping
+
+        self.root_keys.each do |rk|
+          map.root_keys << rk
+        end
+
+        map.cache self.cache
+        map.cache_key &self.cache_key if self.cache_key
+      end
+    end
+
+    def ==(other)
+      methods = %i(properties root_keys mapping cache cache_key)
+      methods.inject(true) do |current_value, method|
+        break unless current_value
+        send(method) == other.send(method)
+      end
+    end
+  end
+end

data/lib/cartograph/property.rb

@@ -0,0 +1,69 @@
+module Cartograph
+  class Property
+    attr_reader :name, :options
+    attr_accessor :map
+
+    def initialize(name, options = {}, &block)
+      @name = name
+      @options = options
+
+      if mapped_class = options[:include]
+        # Perform a safe duplication into our properties map
+        # This allows the user to define more attributes on the map should they need to
+        @map = mapped_class.cartograph.dup
+      end
+
+      if block_given?
+        @map ||= Map.new
+        block.arity > 0 ? block.call(map) : map.instance_eval(&block)
+      end
+    end
+
+    def key
+      (options[:key] || name).to_s
+    end
+
+    def value_for(object, scope = nil)
+      value = object.send(name)
+      return if value.nil?
+      map ? artist_value(value, scope) : value
+    end
+
+    def value_from(object, scope = nil)
+      return if object.nil?
+      value = object.has_key?(key) ? object[key] : object[key.to_sym]
+      map ? sculpt_value(value, scope) : value
+    end
+
+    def scopes
+      Array(options[:scopes] || [])
+    end
+
+    def plural?
+      !!options[:plural]
+    end
+
+    def dup
+      Property.new(name, options.dup).tap do |property|
+        property.map = map.dup if self.map
+      end
+    end
+
+    def ==(other)
+      %i(name options map).inject(true) do |equals, method|
+        break unless equals
+        send(method) == other.send(method)
+      end
+    end
+
+    private
+
+    def sculpt_value(value, scope)
+      plural? ? Array(value).map {|v| Sculptor.new(v, map).sculpt(scope) } : Sculptor.new(value, map).sculpt(scope)
+    end
+
+    def artist_value(value, scope)
+      plural? ? Array(value).map {|v| Artist.new(v, map).draw(scope) } : Artist.new(value, map).draw(scope)
+    end
+  end
+end

data/lib/cartograph/property_collection.rb

@@ -0,0 +1,27 @@
+require 'forwardable'
+
+module Cartograph
+  class PropertyCollection
+    # Make this collection quack like an array
+    # http://words.steveklabnik.com/beware-subclassing-ruby-core-classes
+    extend Forwardable
+    def_delegators :@collection, *(Array.instance_methods - Object.instance_methods)
+
+    def initialize(*)
+      @collection = []
+    end
+
+    def filter_by_scope(scope)
+      select do |property|
+        property.scopes.include?(scope)
+      end
+    end
+
+    def ==(other)
+      each_with_index.inject(true) do |current_value, (property, index)|
+        break unless current_value
+        property == other[index]
+      end
+    end
+  end
+end

data/lib/cartograph/root_key.rb

@@ -0,0 +1,19 @@
+module Cartograph
+  class RootKey
+    attr_reader :options
+
+    def initialize(options = {})
+      @options = options
+    end
+
+    def scopes
+      Array(options[:scopes]) || []
+    end
+
+    %i(singular plural).each do |method|
+      define_method(method) do
+        options[method]
+      end
+    end
+  end
+end

data/lib/cartograph/sculptor.rb

@@ -0,0 +1,40 @@
+module Cartograph
+  class Sculptor
+    attr_reader :object, :map
+
+    def initialize(object, map)
+      @object = object
+      @map = map
+    end
+
+    def properties
+      map.properties
+    end
+
+    # Set this to pass in an object to extract into. Must
+    # @param object must be of the same class as the map#mapping
+    def sculpted_object=(object)
+      raise ArgumentError unless object.is_a?(map.mapping)
+
+      @sculpted_object = object
+    end
+
+    def sculpt(scope = nil)
+      return unless @object
+
+      scoped_properties = scope ? properties.filter_by_scope(scope) : properties
+
+      attributes = scoped_properties.each_with_object({}) do |property, h|
+        h[property.name] = property.value_from(object, scope)
+      end
+
+      return map.mapping.new(attributes) unless @sculpted_object
+
+      attributes.each do |name, val|
+        @sculpted_object[name] = val
+      end
+
+      @sculpted_object
+    end
+  end
+end

data/lib/cartograph/version.rb

@@ -0,0 +1,3 @@
+module Cartograph
+  VERSION = '1.0.0'
+end

data/spec/lib/cartograph/artist_spec.rb

@@ -0,0 +1,115 @@
+require 'spec_helper'
+
+describe Cartograph::Artist do
+  let(:map) { Cartograph::Map.new }
+  let(:properties) { map.properties }
+
+  describe '#initialize' do
+    it 'initializes with an object and a map' do
+      object     = double('object', name: 'hello')
+      properties << Cartograph::Property.new(:name)
+
+      artist = Cartograph::Artist.new(object, map)
+
+      expect(artist.object).to be(object)
+      expect(artist.map).to be(map)
+    end
+  end
+
+  describe '#draw' do
+    it 'returns a hash of mapped properties' do
+      object     = double('object', hello: 'world')
+      properties << Cartograph::Property.new(:hello)
+
+      artist = Cartograph::Artist.new(object, map)
+      masterpiece = artist.draw
+
+      expect(masterpiece).to include('hello' => 'world')
+    end
+
+    it 'raises for a property that the object does not have' do
+      class TestArtistNoMethod; end
+      object = TestArtistNoMethod.new
+      properties << Cartograph::Property.new(:bunk)
+      artist = Cartograph::Artist.new(object, map)
+
+      expect { artist.draw }.to raise_error(ArgumentError).with_message("#{object} does not respond to bunk, so we can't map it")
+    end
+
+    context 'for a property with a key set on it' do
+      it 'returns the hash with the key set correctly' do
+        object     = double('object', hello: 'world')
+        properties << Cartograph::Property.new(:hello, key: :hola)
+
+        artist = Cartograph::Artist.new(object, map)
+        masterpiece = artist.draw
+
+        expect(masterpiece).to include('hola' => 'world')
+      end
+    end
+
+    context 'for filtered drawing' do
+      it 'only returns the scoped properties' do
+        object     = double('object', hello: 'world', foo: 'bar')
+        properties << Cartograph::Property.new(:hello, scopes: [:create, :read])
+        properties << Cartograph::Property.new(:foo, scopes: [:create])
+
+        artist = Cartograph::Artist.new(object, map)
+        masterpiece = artist.draw(:read)
+
+        expect(masterpiece).to eq('hello' => 'world')
+      end
+
+      context 'on nested properties' do
+        it 'only returns the nested properties within the same scope' do
+          child = double('child', hello: 'world', foo: 'bunk')
+          object = double('object', child: child)
+
+          root_property = Cartograph::Property.new(:child, scopes: [:create, :read]) do
+            property :hello, scopes: [:create]
+            property :foo, scopes: [:read]
+          end
+
+          properties << root_property
+
+          artist = Cartograph::Artist.new(object, map)
+          masterpiece = artist.draw(:read)
+
+          expect(masterpiece).to eq('child' => { 'foo' => child.foo })
+        end
+      end
+    end
+
+    context "with caching enabled" do
+      let(:cacher) { double('cacher', fetch: { foo: 'cached-value' }) }
+      let(:object) { double('object', foo: 'bar', cache_key: 'test-cache-key') }
+
+      it "uses the cache fetch for values" do
+        map.cache(cacher)
+        map.cache_key { |obj, scope| obj.cache_key }
+        map.property :foo
+
+        artist = Cartograph::Artist.new(object, map)
+        masterpiece = artist.draw
+
+        expect(masterpiece).to eq(cacher.fetch)
+
+        expect(cacher).to have_received(:fetch).with('test-cache-key')
+      end
+
+      it "uses the cache key for the object and scope" do
+        called = double(call: 'my-cache')
+
+        map.cache(cacher)
+        map.cache_key { |obj, scope| called.call(obj, scope) }
+
+        map.property :foo, scopes: [:read]
+
+        artist = Cartograph::Artist.new(object, map)
+        masterpiece = artist.draw(:read)
+
+        expect(called).to have_received(:call).with(object, :read)
+      end
+    end
+  end
+end