kartograph 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b3a8357794a9b9db82e82cfc2f40c34096392c54
-  data.tar.gz: ea222705a629a01c14c74fdc71ff341c8fd38f96
+  metadata.gz: d0486e484ee7a91e233645567afcf28f2ff25d6b
+  data.tar.gz: 0b6232dbd15c7a27a90f89b00652abdc4912a789
 SHA512:
-  metadata.gz: 9290c302a911fedd70604881bbd338c6f23e7ace3e3ca93d85fbb7cabbe83af1952636b8291c0a5013113b2878b8a5dba9d441eb01b6adc7990ea4bcd1da090b
-  data.tar.gz: cf8c415714bc1dc47b585af1289d6b713640dff5d8eb0921ee5b2e6300e45d5f25c0885e327fed34dd9152c6ca0ceb53780c91f8188b1239b67a6ec7af711f07
+  metadata.gz: 389d7c025aad932d0f22e2d5b3fa1d03d907bd5af1cb06d916549af5caadfc10c47ee975ef3a0d5c4c9de6ea093bfc039bf2b9dccd8e34345ca5a9f5a6c0d994
+  data.tar.gz: aeff8daa983de66a69c76a7c73e995d91ce28b977c2749c7eba257ecda38294ba6d4653eb0f16c03f8bcac860003cd4b072dc44cecd1e25d1cb265d7a1f6092a

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/README.md

@@ -18,7 +18,98 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Kartograph makes it easy to generate and convert JSON. It's intention is to be used for API clients.
+
+For example, if you have an object that you would like to convert to JSON for a create request to an API. You would have something similar to this:
+
+```ruby
+class UserMapping
+  include Kartograph::DSL
+
+  kartograph do
+    mapping User # The object we're mapping
+
+    property :name, scopes: [:create, :update]
+    property :id, scopes: [:read]
+  end
+end
+
+user = User.new(name: 'Bobby Tables')
+json_for_create = UserMapping.representation_for(:create, user)
+```
+
+Some API's will give you the created resource back as JSON as well on a successful create. For that, you may do something like this:
+
+```ruby
+response = HTTPClient.post("http://something.com/api/users", body: json_for_create)
+created_user = UserMapping.extract_single(response.body, :read)
+```
+
+Most API's will have a way of retrieving an entire resource collection. For this you can instruct Kartograph to convert a collection.
+
+```ruby
+response = HTTPClient.get("http://something.com/api/users")
+users = UserMapping.extract_collection(response.body, :read)
+# => [ User, User, User ]
+```
+
+### Getting Harder
+
+Sometimes resources will nest other properties under a key. Kartograph can handle this as well.
+
+```ruby
+class UserMapping
+  include Kartograph::DSL
+
+  kartograph do
+    mapping User # The object we're mapping
+
+    property :name, scopes: [:read]
+
+    property :comments do
+      mapping Comment # The nested object we're mapping
+
+      property :text, scopes: [:read]
+      property :author, scopes: [:read]
+    end
+  end
+end
+```
+
+Just like the previous examples, when you serialize this. It will include the comment block for the scope defined.
+
+### Root Keys
+
+Kartograph can also handle the event of root keys in response bodies. For example, if you receive a response with:
+
+```json
+{ "user": { "id": 123 } }
+```
+
+You could define a mapping like this:
+
+
+```ruby
+class UserMapping
+  include Kartograph::DSL
+
+  kartograph do
+    mapping User
+    root_key singular: 'user', plural: 'users' scopes: [:read]
+    property :id, scopes: [:read]
+  end
+end
+```
+
+This means that when you call the same thing:
+
+```ruby
+response = HTTPClient.get("http://something.com/api/users")
+users = UserMapping.extract_collection(response.body, :read)
+```
+
+It will look for the root key before trying to deserialize the JSON response.
+The advantage of this is it will only use the root key if there is a scope defined for it.
 
 ## Contributing
 

data/examples/domains.rb

@@ -0,0 +1,54 @@
+require 'kartograph'
+
+json = '{
+  "domains": [
+    {
+      "name": "example.com",
+      "ttl": 1800,
+      "zone_file": "Example zone file text..."
+    }
+  ],
+  "meta": {
+    "total": 1
+  }
+}'
+
+class Domain
+  attr_accessor :name, :ttl, :zone_file
+end
+
+class MetaInformation
+  attr_accessor :total
+end
+
+class DomainMapper
+  include Kartograph::DSL
+
+  kartograph do
+    mapping Domain
+    root_key singular: 'domain', plural: 'domains', scopes: [:read]
+
+    property :name, scopes: [:read]
+    property :ttl, scopes: [:read]
+    property :zone_file, scopes: [:read]
+  end
+end
+
+class MetaInformationMapper
+  include Kartograph::DSL
+
+  kartograph do
+    mapping MetaInformation
+
+    root_key singular: 'meta', scopes: [:read]
+    property :total, scopes: [:read]
+  end
+end
+
+domains = DomainMapper.extract_collection(json, :read)
+meta = MetaInformationMapper.extract_single(json, :read)
+
+puts "Total Domains: #{domains.size}"
+puts domains.map(&:name)
+puts
+puts "Total pages: #{meta.total}"

data/examples/representation_for.rb

@@ -0,0 +1,24 @@
+class Domain
+  attr_accessor :name, :ttl, :zone_file
+end
+
+class DomainMapper
+  include Kartograph::DSL
+
+  kartograph do
+    mapping Domain
+    root_key singular: 'domain', plural: 'domains', scopes: [:read]
+
+    property :name, scopes: [:read, :create]
+    property :ttl, scopes: [:read, :create]
+    property :zone_file, scopes: [:read]
+  end
+end
+
+domain = Domain.new
+domain.name = 'example.com'
+domain.ttl = 3600
+domain.zone_file = "this wont be represented for create"
+
+puts DomainMapper.representation_for(:create, domain)
+#=> {"name":"example.com","ttl":3600}

data/kartograph.gemspec

@@ -21,4 +21,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.6"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec", "~> 3.0.0"
+  spec.add_development_dependency "pry"
 end

data/lib/kartograph.rb

@@ -1,5 +1,13 @@
 require "kartograph/version"
+require 'json'
 
 module Kartograph
-  # Your code goes here...
+  autoload :DSL, 'kartograph/dsl'
+  autoload :Map, 'kartograph/map'
+  autoload :Property, 'kartograph/property'
+  autoload :PropertyCollection, 'kartograph/property_collection'
+  autoload :RootKey, 'kartograph/root_key'
+
+  autoload :Artist, 'kartograph/artist'
+  autoload :Sculptor, 'kartograph/sculptor'
 end

data/lib/kartograph/artist.rb

@@ -0,0 +1,22 @@
+module Kartograph
+  class Artist
+    attr_reader :object, :map
+
+    def initialize(object, map)
+      @object = object
+      @map = map
+    end
+
+    def properties
+      map.properties
+    end
+
+    def draw(scope = nil)
+      scoped_properties = scope ? properties.filter_by_scope(scope) : properties
+      scoped_properties.each_with_object({}) do |property, mapped|
+        raise ArgumentError, "#{object} does not respond to #{property.name}, so we can't map it" unless object.respond_to?(property.name)
+        mapped[property.name] = property.value_for(object, scope)
+      end
+    end
+  end
+end

data/lib/kartograph/dsl.rb

@@ -0,0 +1,58 @@
+module Kartograph
+  module DSL
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      def kartograph(&block)
+        @kartograph_map ||= Map.new
+
+        block.arity > 0 ? block.call(@kartograph_map) : @kartograph_map.instance_eval(&block)
+      end
+
+      def representation_for(scope, object, dumper = JSON)
+        drawed = Artist.new(object, @kartograph_map).draw(scope)
+
+        retrieve_root_key(scope, :singular) do |root_key|
+          # Reassign drawed if a root key exists
+          drawed = { root_key => drawed }
+        end
+
+        dumper.dump(drawed)
+      end
+
+      def extract_single(content, scope, loader = JSON)
+        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, @kartograph_map).sculpt(scope)
+      end
+
+      def extract_collection(content, scope, loader = JSON)
+        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, @kartograph_map).sculpt(scope)
+        end
+      end
+
+      private
+
+      def retrieve_root_key(scope, type, &block)
+        if root_key = @kartograph_map.root_key_for(scope, type)
+          yield root_key
+        end
+      end
+    end
+  end
+end

data/lib/kartograph/map.rb

@@ -0,0 +1,32 @@
+module Kartograph
+  class Map
+    def property(*args, &block)
+      properties << Property.new(*args, &block)
+    end
+
+    def properties
+      @properties ||= PropertyCollection.new
+    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 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
+  end
+end

data/lib/kartograph/property.rb

@@ -0,0 +1,43 @@
+module Kartograph
+  class Property
+    attr_reader :name, :options, :map
+
+    def initialize(name, options = {}, &block)
+      @name = name
+      @options = options
+
+      if block_given?
+        @map ||= Map.new
+        block.arity > 0 ? block.call(map) : map.instance_eval(&block)
+      end
+    end
+
+    def value_for(object, scope = nil)
+      value = object.send(name)
+      map ? artist_value(value, scope) : value
+    end
+
+    def value_from(object, scope = nil)
+      value = object.has_key?(name) ? object[name] : object[name.to_s]
+      map ? sculpt_value(value, scope) : value
+    end
+
+    def scopes
+      options[:scopes] || []
+    end
+
+    def plural?
+      !!options[:plural]
+    end
+
+    private
+
+    def sculpt_value(value, scope)
+      plural? ? value.map {|v| Sculptor.new(v, map).sculpt(scope) } : Sculptor.new(value, map).sculpt(scope)
+    end
+
+    def artist_value(value, scope)
+      plural? ? value.map {|v| Artist.new(v, map).draw(scope) } : Artist.new(value, map).draw(scope)
+    end
+  end
+end

data/lib/kartograph/property_collection.rb

@@ -0,0 +1,20 @@
+require 'forwardable'
+
+module Kartograph
+  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
+  end
+end

data/lib/kartograph/root_key.rb

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

data/lib/kartograph/sculptor.rb

@@ -0,0 +1,26 @@
+module Kartograph
+  class Sculptor
+    attr_reader :object, :map
+
+    def initialize(object, map)
+      @object = object
+      @map = map
+    end
+
+    def properties
+      map.properties
+    end
+
+    def sculpt(scope = nil)
+      # Initializing the object we're coercing so we can set attributes on it
+      coerced = map.mapping.new
+      scoped_properties = scope ? properties.filter_by_scope(scope) : properties
+
+      scoped_properties.each_with_object(coerced) do |property, mutable|
+        setter_method = "#{property.name}="
+        value = property.value_from(object, scope)
+        mutable.send(setter_method, value)
+      end
+    end
+  end
+end

data/lib/kartograph/version.rb

@@ -1,3 +1,3 @@
 module Kartograph
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/spec/lib/kartograph/artist_spec.rb

@@ -0,0 +1,70 @@
+require 'spec_helper'
+
+describe Kartograph::Artist do
+  let(:map) { Kartograph::Map.new }
+  let(:properties) { map.properties }
+
+  describe '#initialize' do
+    it 'initializes with an object and a map' do
+      object     = double('object', name: 'hello')
+      properties << Kartograph::Property.new(:name)
+
+      artist = Kartograph::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 << Kartograph::Property.new(:hello)
+
+      artist = Kartograph::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
+      object = double('object')
+      properties << Kartograph::Property.new(:bunk)
+      artist = Kartograph::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 filtered drawing' do
+      it 'only returns the scoped properties' do
+        object     = double('object', hello: 'world', foo: 'bar')
+        properties << Kartograph::Property.new(:hello, scopes: [:create, :read])
+        properties << Kartograph::Property.new(:foo, scopes: [:create])
+
+        artist = Kartograph::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 = Kartograph::Property.new(:child, scopes: [:create, :read]) do
+            property :hello, scopes: [:create]
+            property :foo, scopes: [:read]
+          end
+
+          properties << root_property
+
+          artist = Kartograph::Artist.new(object, map)
+          masterpiece = artist.draw(:read)
+
+          expect(masterpiece).to eq(child: { foo: child.foo })
+        end
+      end
+    end
+  end
+end

data/spec/lib/kartograph/dsl_spec.rb

@@ -0,0 +1,125 @@
+require 'spec_helper'
+
+describe Kartograph::DSL do
+  describe 'Inclusion' do
+    it 'gives you a class method for .kartograph' do
+      klass = Class.new
+      expect { klass.send(:include, described_class) }.to change { klass.respond_to?(:kartograph) }.to(true)
+    end
+  end
+
+  describe '.kartograph' do
+    subject(:mapping) { Class.new { include Kartograph::DSL } }
+
+    it 'yields a Kartograph::Map instance' do
+      expect {|b| mapping.kartograph(&b) }.to yield_with_args(instance_of(Kartograph::Map))
+    end
+  end
+
+  describe '.representation_for' do
+    include_context 'DSL Objects'
+
+    it 'returns the JSON representation for an object' do
+      json = mapped.representation_for(:create, object)
+      expect(json).to eq(
+        { name: object.name }.to_json
+      )
+    end
+
+    context 'with a root key for the scope' do
+      it 'returns the json with the root key' do
+        mapped.kartograph do
+          root_key singular: 'user', scopes: [:create]
+        end
+        json = mapped.representation_for(:create, object)
+
+        expect(json).to eq(
+          {
+            user: {
+              name: object.name
+            }
+          }.to_json
+        )
+      end
+    end
+  end
+
+  describe '.extract_single' do
+    include_context 'DSL Objects'
+    let(:json) do
+      { id: 1337, name: 'Paul the octopus' }
+    end
+
+    it 'returns a populated object from a JSON representation' do
+      extracted = mapped.extract_single(json.to_json, :read)
+
+      expect(extracted.id).to eq(1337)
+      expect(extracted.name).to eq('Paul the octopus')
+    end
+
+    context 'with a root key in the JSON' do
+      let(:json) { { test: super() } }
+
+      before do
+        mapped.kartograph do
+          root_key singular: 'test', scopes: [:read]
+        end
+      end
+
+      it 'traverses into the key and pulls the object from there' do
+        extracted = mapped.extract_single(json.to_json, :read)
+
+        expect(extracted.id).to eq(1337)
+        expect(extracted.name).to eq('Paul the octopus')
+      end
+    end
+  end
+
+  describe '.extract_collection' do
+    include_context 'DSL Objects'
+    let(:json) do
+      [
+        { id: 1337, name: 'Paul the octopus' },
+        { id: 1338, name: 'Hank the octopus' }
+      ]
+    end
+
+    it 'returns a collection of objects from the json' do
+      extracted = mapped.extract_collection(json.to_json, :read)
+
+      expect(extracted.size).to be(2)
+      expect(extracted).to all(be_kind_of(DummyUser))
+
+      expect(extracted[0].id).to eq(json[0][:id])
+      expect(extracted[0].name).to eq(json[0][:name])
+
+      expect(extracted[1].id).to eq(json[1][:id])
+      expect(extracted[1].name).to eq(json[1][:name])
+    end
+
+    context 'for a nested key' do
+      let(:json) { { users: super() } }
+
+      before do
+        mapped.kartograph do
+          root_key plural: 'users', scopes: [:read]
+        end
+      end
+
+      it 'returns a collection of objects from the json' do
+        extracted = mapped.extract_collection(json.to_json, :read)
+
+        expect(extracted.size).to be(2)
+        expect(extracted).to all(be_kind_of(DummyUser))
+
+        scoped = json[:users]
+
+        expect(extracted[0].id).to eq(scoped[0][:id])
+        expect(extracted[0].name).to eq(scoped[0][:name])
+
+        expect(extracted[1].id).to eq(scoped[1][:id])
+        expect(extracted[1].name).to eq(scoped[1][:name])
+      end
+    end
+  end
+end

data/spec/lib/kartograph/map_spec.rb

@@ -0,0 +1,46 @@
+require 'spec_helper'
+
+describe Kartograph::Map do
+  subject(:map) { Kartograph::Map.new }
+
+  describe '#property' do
+    it 'adds a property to the map' do
+      map.property :attribute_name, scopes: [:read]
+      expect(map.properties.size).to be(1)
+      expect(map.properties.first).to be_kind_of(Kartograph::Property)
+    end
+  end
+
+  describe '#properties' do
+    it 'returns a PropertyCollection object' do
+      properties = map.properties
+      expect(properties).to be_kind_of(Kartograph::PropertyCollection)
+    end
+  end
+
+  describe '#mapping' do
+    it 'sets the class we\'re mapping' do
+      map.mapping Class
+      expect(map.mapping).to be(Class)
+    end
+  end
+
+  describe '#root_key' do
+    it 'sets the root keys' do
+      map.root_key singlular: 'test', scopes: [:read]
+      map.root_key singlular: 'test', scopes: [:create]
+
+      expect(map.root_keys.size).to be(2)
+      expect(map.root_keys).to all(be_kind_of(Kartograph::RootKey))
+    end
+  end
+
+  describe '#root_key_for' do
+    it 'returns the first root key for the scope and type' do
+      map.root_key singular: 'test', scopes: [:read]
+      key = map.root_key_for(:read, :singular)
+
+      expect(key).to eq('test')
+    end
+  end
+end

data/spec/lib/kartograph/property_collection_spec.rb

@@ -0,0 +1,15 @@
+require 'spec_helper'
+
+describe Kartograph::PropertyCollection do
+  describe '#filter_by_scope' do
+    it 'only returns properties with a certain scope attached' do
+      collection = Kartograph::PropertyCollection.new
+      collection << Kartograph::Property.new(:hello, scopes: [:read, :create])
+      collection << Kartograph::Property.new(:id, scopes: [:read])
+
+      filtered = collection.filter_by_scope(:create)
+      expect(filtered.size).to be(1)
+      expect(filtered.first.name).to eq(:hello)
+    end
+  end
+end

data/spec/lib/kartograph/property_spec.rb

@@ -0,0 +1,155 @@
+require 'spec_helper'
+
+describe Kartograph::Property do
+  describe '#initialize' do
+    it 'initializes with an attribute name and options' do
+      name = :hey
+      options = { lol: 'whut' }
+
+      property = Kartograph::Property.new(name, options)
+      expect(property.name).to eq(name)
+      expect(property.options).to eq(options)
+    end
+
+    context 'with a block' do
+      it 'yields a map instance for the property' do
+        expect {|b| Kartograph::Property.new(:hello, &b) }.to yield_with_args(instance_of(Kartograph::Map))
+      end
+    end
+  end
+
+  describe '#scopes' do
+    it 'returns the scopes that the property is for' do
+      property = Kartograph::Property.new(:name, scopes: [:read, :create])
+      expect(property.scopes).to include(:read, :create)
+    end
+
+    it 'returns an empty array when no scopes are provided' do
+      property = Kartograph::Property.new(:name)
+      expect(property.scopes).to eq( [] )
+    end
+  end
+
+  describe '#plural?' do
+    it 'returns true when set to plural' do
+      property = Kartograph::Property.new(:name, scopes: [:read], plural: true)
+      expect(property).to be_plural
+    end
+
+    it 'returns false when not set' do
+      property = Kartograph::Property.new(:name, scopes: [:read])
+      expect(property).to_not be_plural
+    end
+  end
+
+  describe '#value_for' do
+    it 'returns the value when passed an object' do
+      property = Kartograph::Property.new(:sammy)
+      object = double('object', sammy: 'cephalopod')
+
+      expect(property.value_for(object)).to eq('cephalopod')
+    end
+
+    context 'for a nested property set' do
+      it 'returns nested properties' do
+        top_level = Kartograph::Property.new(:sammy) do
+          property :cephalopod
+        end
+
+        child = double('child', cephalopod: 'I will ink you')
+        root = double('root', sammy: child)
+
+        expect(top_level.value_for(root)).to eq(cephalopod: child.cephalopod)
+      end
+
+      context 'when it is plural' do
+        it 'returns a pluralized representation' do
+          top_level = Kartograph::Property.new(:sammy, plural: true) do
+            property :cephalopod
+          end
+
+          child1 = double('child', cephalopod: 'I will ink you')
+          child2 = double('child', cephalopod: 'I wont because im cool')
+
+          root = double('root', sammy: [child1, child2])
+
+          expect(top_level.value_for(root)).to eq([
+            { cephalopod: child1.cephalopod },
+            { cephalopod: child2.cephalopod }
+          ])
+        end
+      end
+    end
+  end
+
+  describe '#value_from' do
+    let(:hash) { { hello: 'world' } }
+
+    it 'retrieves the value from a hash for the property' do
+      property = Kartograph::Property.new(:hello)
+      expect(property.value_from(hash)).to eq('world')
+    end
+
+    context 'string and symbol agnostic' do
+      let(:hash) { { 'hello' => 'world' } }
+
+      it 'retrieves the value from a hash for the property' do
+        property = Kartograph::Property.new(:hello)
+        expect(property.value_from(hash)).to eq('world')
+      end
+    end
+
+    context 'for a nested property set' do
+      it 'returns an object with the properties set on it' do
+        dummy_class = Struct.new(:id, :name)
+
+        nested_property = Kartograph::Property.new(:hello) do
+          mapping dummy_class
+          property :id
+          property :name
+        end
+
+        hash = { hello: {
+          'id' => 555,
+          'name' => 'Buckstar'
+        }}
+
+        value = nested_property.value_from(hash)
+        expect(value).to be_kind_of(dummy_class)
+        expect(value.id).to eq(hash[:hello]['id'])
+        expect(value.name).to eq(hash[:hello]['name'])
+      end
+
+      it 'returns a collection of objects when set to plural' do
+        dummy_class = Struct.new(:id, :name)
+
+        nested_property = Kartograph::Property.new(:hello, plural: true) do
+          mapping dummy_class
+
+          property :id
+          property :name
+        end
+
+        hash = {
+          hello: [{
+            'id' => 555,
+            'name' => 'Buckstar'
+          }, {
+            'id' => 556,
+            'name' => 'Starbuck'
+          }]
+        }
+
+        value = nested_property.value_from(hash)
+        expect(value).to be_kind_of(Array)
+        expect(value.size).to be(2)
+
+        expect(value[0].id).to eq(hash[:hello][0]['id'])
+        expect(value[0].name).to eq(hash[:hello][0]['name'])
+
+        expect(value[1].id).to eq(hash[:hello][1]['id'])
+        expect(value[1].name).to eq(hash[:hello][1]['name'])
+      end
+    end
+  end
+end

data/spec/lib/kartograph/root_key_spec.rb

@@ -0,0 +1,33 @@
+require 'spec_helper'
+
+describe Kartograph::RootKey do
+  describe '#initialize' do
+    it 'initializes with options' do
+      options = { singular: 'hello', plural: 'hellos', scopes: [:read] }
+
+      instance = Kartograph::RootKey.new(options)
+      expect(instance.options).to eq(options)
+    end
+  end
+
+  describe '#scopes' do
+    it 'reads the scopes' do
+      instance = Kartograph::RootKey.new(scopes: [:read])
+      expect(instance.scopes).to eq([:read])
+    end
+  end
+
+  describe '#singular' do
+    it 'reads the singular key' do
+      instance = Kartograph::RootKey.new(singular: 'user')
+      expect(instance.singular).to eq('user')
+    end
+  end
+
+  describe '#plural' do
+    it 'reads the plural key' do
+      instance = Kartograph::RootKey.new(plural: 'user')
+      expect(instance.plural).to eq('user')
+    end
+  end
+end

data/spec/lib/kartograph/sculptor_spec.rb

@@ -0,0 +1,76 @@
+require 'spec_helper'
+
+describe Kartograph::Sculptor do
+  describe '#initialize' do
+    it 'initializes with a hash and map' do
+      hash = {}
+      map = double('im a map')
+
+      sculptor = Kartograph::Sculptor.new(hash, map)
+
+      expect(sculptor.object).to be(hash)
+      expect(sculptor.map).to be(map)
+    end
+  end
+
+  describe '#sculpt' do
+    let(:map) { Kartograph::Map.new }
+    let(:object) { { 'id' => 343, 'name' => 'Guilty Spark' } }
+
+    context 'without a scope' do
+      before do
+        map.mapping DummyUser
+        map.property :id, scopes: [:read]
+        map.property :name, scopes: [:read, :create]
+      end
+
+      it 'returns a coerced user' do
+        sculptor = Kartograph::Sculptor.new(object, map)
+        sculpted = sculptor.sculpt
+
+        expect(sculpted).to be_kind_of(DummyUser)
+        expect(sculpted.id).to eq(object['id'])
+        expect(sculpted.name).to eq(object['name'])
+      end
+    end
+
+    context 'with a scope' do
+      before do
+        map.mapping DummyUser
+        map.property :id, scopes: [:read]
+        map.property :name, scopes: [:create]
+      end
+
+      it 'returns a coerced user' do
+        sculptor = Kartograph::Sculptor.new(object, map)
+        sculpted = sculptor.sculpt(:read)
+
+        expect(sculpted).to be_kind_of(DummyUser)
+        expect(sculpted.id).to eq(object['id'])
+        expect(sculpted.name).to be_nil
+      end
+
+      context 'for nested properties' do
+        let(:object) { super().merge('comment' => { 'id' => 123, 'text' => 'hello' }) }
+
+        before do
+          map.property :comment, scopes: [:read] do
+            mapping DummyComment
+
+            property :id, scopes: [:read]
+            property :text, scopes: [:create]
+          end
+        end
+
+        it 'returns the nested objects with scoped properties set' do
+          sculptor = Kartograph::Sculptor.new(object, map)
+          sculpted = sculptor.sculpt(:read)
+
+          expect(sculpted.comment).to be_kind_of(DummyComment)
+          expect(sculpted.comment.id).to eq(123)
+          expect(sculpted.comment.text).to be_nil
+        end
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,66 @@
+require 'kartograph'
+
+Dir['./spec/support/**/*.rb'].each {|f| load f }
+
+RSpec.configure do |config|
+# The settings below are suggested to provide a good initial experience
+# with RSpec, but feel free to customize to your heart's content.
+=begin
+  # These two settings work together to allow you to limit a spec run
+  # to individual examples or groups you care about by tagging them with
+  # `:focus` metadata. When nothing is tagged with `:focus`, all examples
+  # get run.
+  config.filter_run :focus
+  config.run_all_when_everything_filtered = true
+
+  # Many RSpec users commonly either run the entire suite or an individual
+  # file, and it's useful to allow more verbose output when running an
+  # individual spec file.
+  if config.files_to_run.one?
+    # Use the documentation formatter for detailed output,
+    # unless a formatter has already been configured
+    # (e.g. via a command-line flag).
+    config.default_formatter = 'doc'
+  end
+
+  # Print the 10 slowest examples and example groups at the
+  # end of the spec run, to help surface which specs are running
+  # particularly slow.
+  config.profile_examples = 10
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = :random
+
+  # Seed global randomization in this process using the `--seed` CLI option.
+  # Setting this allows you to use `--seed` to deterministically reproduce
+  # test failures related to randomization by passing the same `--seed` value
+  # as the one that triggered the failure.
+  Kernel.srand config.seed
+
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # Enable only the newer, non-monkey-patching expect syntax.
+    # For more details, see:
+    #   - http://myronmars.to/n/dev-blog/2012/06/rspecs-new-expectation-syntax
+    expectations.syntax = :expect
+  end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Enable only the newer, non-monkey-patching expect syntax.
+    # For more details, see:
+    #   - http://teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
+    mocks.syntax = :expect
+
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended.
+    mocks.verify_partial_doubles = true
+  end
+=end
+end

data/spec/support/dsl_contexts.rb

@@ -0,0 +1,22 @@
+shared_context "DSL Objects" do
+  let(:object) { double('object', id: 1066, name: 'Bruce (the dude from Finding Nemo)') }
+  let(:mapped) do
+    Class.new do
+      include Kartograph::DSL
+
+      kartograph do
+        mapping DummyUser
+
+        property :id, scopes: [:read]
+        property :name, scopes: [:read, :create]
+
+        property :comments, plural: true do
+          mapping DummyComment
+
+          property :id, scopes: [:read]
+          property :text, scopes: [:read, :create]
+        end
+      end
+    end
+  end
+end

data/spec/support/dummy_comment.rb

@@ -0,0 +1,2 @@
+class DummyComment < Struct.new(:id, :text)
+end

data/spec/support/dummy_user.rb

@@ -0,0 +1,2 @@
+class DummyUser < Struct.new(:id, :name, :comment)
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kartograph
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Robert Ross
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-29 00:00:00.000000000 Z
+date: 2014-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,20 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Short Description
 email:
 - rross@digitalocean.com
@@ -60,13 +74,34 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .rspec
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- examples/domains.rb
+- examples/representation_for.rb
 - kartograph.gemspec
 - lib/kartograph.rb
+- lib/kartograph/artist.rb
+- lib/kartograph/dsl.rb
+- lib/kartograph/map.rb
+- lib/kartograph/property.rb
+- lib/kartograph/property_collection.rb
+- lib/kartograph/root_key.rb
+- lib/kartograph/sculptor.rb
 - lib/kartograph/version.rb
+- spec/lib/kartograph/artist_spec.rb
+- spec/lib/kartograph/dsl_spec.rb
+- spec/lib/kartograph/map_spec.rb
+- spec/lib/kartograph/property_collection_spec.rb
+- spec/lib/kartograph/property_spec.rb
+- spec/lib/kartograph/root_key_spec.rb
+- spec/lib/kartograph/sculptor_spec.rb
+- spec/spec_helper.rb
+- spec/support/dsl_contexts.rb
+- spec/support/dummy_comment.rb
+- spec/support/dummy_user.rb
 homepage: ''
 licenses:
 - MIT
@@ -91,4 +126,15 @@ rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Short Summary
-test_files: []
+test_files:
+- spec/lib/kartograph/artist_spec.rb
+- spec/lib/kartograph/dsl_spec.rb
+- spec/lib/kartograph/map_spec.rb
+- spec/lib/kartograph/property_collection_spec.rb
+- spec/lib/kartograph/property_spec.rb
+- spec/lib/kartograph/root_key_spec.rb
+- spec/lib/kartograph/sculptor_spec.rb
+- spec/spec_helper.rb
+- spec/support/dsl_contexts.rb
+- spec/support/dummy_comment.rb
+- spec/support/dummy_user.rb