spigot 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a336365a8fdebfc3d1bd45fa11afea3c0a489ba6
-  data.tar.gz: 30a5f6d8ce9c7fce3644233db8d35ff57cc45f17
+  metadata.gz: c6e0174fc401969ff57755d4eb751c1ebb3bd5c5
+  data.tar.gz: 2844483e9860825c20e4e6b6d255ffe80586843c
 SHA512:
-  metadata.gz: b9df09433c59668681cfe6bd9ddb3c1c591b9e3d31c0aff96596477da1ca6144ecd94f1fcbed2b587a54e47bd6d2596cf9bfd6258020939d5229831c31711d96
-  data.tar.gz: e725567b5260a2b0d9e358191cdb5dee627c6a36e844d49582de010d3f1795e8a6d2dcb8e304ece3e24962de3752aa9a78cf1d369a813f55d9faaed5e2b49a11
+  metadata.gz: 6edf56a3600624852a424f314faf8a1b092eb77a3e216e894964972a081a86348033f52f485540a0970a3c006683a91e7ebfcdba39a5ab9b6c489e08dd34d7ee
+  data.tar.gz: a88764f01212671cf27efdcf1d12218ceec4915b49c767c17b2b1b8560cabefc7ddca0e9ea7ab93686fe1d36f95d9f035cb46c793bd7077d0181eb57094cfc89

data/README.md

@@ -1,45 +1,38 @@
 # Spigot
 
-Spigot provides a clean interface translating API data into context relevant objects
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-    gem 'spigot'
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install spigot
-
-## Usage
+Spigot is an attempt to bring some sanity to consuming external API data. Without Spigot, you need
+to do this manual mapping at creation, such as:
+
+    Pull.where(number: pull.number).first_or_initialize.tap do |t|
+      t.title      = pull.title
+      t.body       = pull.body
+      t.url        = pull._links.html.href
+      t.head_ref   = pull.head.ref
+      t.head_sha   = pull.head.sha
+      t.base_ref   = pull.base.ref
+      t.base_sha   = pull.base.sha
+      t.save
+    end
 
-You express the mapping between your model's data and the data received from an API in
-a yaml file. The mappings follow the structure of the data received. Any attribute you wish
-to retain, assign the name of your model's attribute to the name of the key received.
+Spigot reads config files in an expected format to map the data you receive to the columns of your database.
+This becomes particularly difficult as you start having multiple sources for the same resource (ex: users).
 
-Remember, the key is their attribute, the value is yours:
+Spigot is able to do the translation for you and put the API data into a language your implementation understands.
+This leaves you with a simple statement to accomplish the same as above:
 
-    user:
-      login: 'email'
-      full_name: 'name'
+    Pull.find_or_create_by_api(:github, pull)
 
-Reads as: "For Users, their `login` is my `email` and their `full_name` is my `name`"
+Much better. [Read More](https://github.com/mwerner/spigot/wiki)
 
 ## Example
 
     # Our Model
-    class User
+    class User < ActiveRecord::Base
       include Spigot::Base
-      attr_accessor :name, :email, :auth
     end
 
     # Api Data Received
-    data = {"full_name":"Dean Martin","login":"dino@amore.io","token":"abc123"}
+    data = JSON.parse("{\"full_name\":\"Dean Martin\",\"login\":\"dino@amore.io\",\"token\":\"abc123\"}")
 
     # Spigot yaml file to map this data correctly
     user:
@@ -48,169 +41,22 @@ Reads as: "For Users, their `login` is my `email` and their `full_name` is my `n
       token: auth
 
     # Usage
-    User.new_by_api(data).inspect
-    #=> #<User:0x007ffa2918c7b8 @name="Dean Martin", @email="dino@amore.io", @auth="abc123">
-
-## Map Format
-
-Each Spigot map file represents one service, with as many resources defined as you like.
-
-##### Basic Map
-
-    user:
-      name: 'full_name'
-      email: 'login'
-      username: 'username'
-
-##### Multiple Resources
-
-Spigot will look up the map for the name of the class implementing the method. This let's you map
-several of your resources that you're getting from the same service.
-
-    # ./config/github.yml
-    user:
-      name: 'full_name'
-      email: 'login'
-      username: 'username'
-
-    post:
-      title: 'title'
-      body: 'description'
-      created_at: 'timestamp'
-
-##### Options
-
-Spigot will look for an options key named `spigot` in the defined map.
-Those options let you configure additional options for that resource,
-such as denoting the identification in the data received.
-
-    user:
-      name: 'full_name'
-      email: 'login'
-      username: 'username'
-      spigot:
-        primary_key: 'service_id'
-        foreign_key: 'id'
-
-## ActiveRecord
-
-If you include Spigot on an ActiveRecord class, you get a few more methods.
-
-##### `find_by_api`
-
-This uses the primary key defined in that resource's options to query the database
-with the value taken from the api data. (**Note** Does not update any values on the
-record received from the database.)
-
-    # Spigot yaml file for the github service
-    user:
-      full_name: name
-      login: email
-      token: auth
-      spigot:
-        primary_key: email
-
-    # API Data
-    data = {"full_name":"Dean","login":"dino@amore.io","token":"bcd456"}
-
-    #=> User.find_by_api(:github, data)
-    User Load (0.1ms)  SELECT "users".* FROM "users" WHERE "users"."email" = 'dino@amore.io' ORDER BY "users"."id" ASC LIMIT 1
+    User.find_or_create_by_api(:github, data).inspect
     #=> #<User id: 1, name: "Dean Martin", email: "dino@amore.io", token: "abc123">
 
-##### `find_all_by_api`
-
-Operates just like `find_by_api`, but returns all matches on the primary key. The method
-returns an `ActveRecord::Relation` allowing you to chain other constraints if you need.
-
-    # Spigot yaml file for the github service
-    user:
-      full_name: name
-      login: email
-      token: auth
-      spigot:
-        primary_key: full_name
-
-    # API Data
-    data = {"full_name":"Dean","login":"dino@amore.io","token":"bcd456"}
-
-    #=> User.find_all_by_api(:github, data)
-    User Load (0.1ms)  SELECT "users".* FROM "users" WHERE "users"."name" = 'Dean'
-    => #<ActiveRecord::Relation [#<User id: 1, name: "Dean", email: "dino@amore.io", token: "abc123">, #<User id: 2, name: "Dean", email: "minerals@notrocks.io", token: '92fnd'>]>
-
-##### `create_by_api`
-
-Creates a record in your database using the provided API data, without doing
-any kind of query before, beyond your model's defined validations. Notice the
-creation does not use any of the API that isn't defined in the map.
-
-    # Spigot yaml file for the github service
-    user:
-      full_name: name
-      login: email
-      token: auth
-      spigot:
-        primary_key: email
-
-    # API Data
-    data = {"full_name":"Frank Sinatra","login":"live@tilidie.io","id":"3"}
-
-    #=> User.create_by_api(:github, data)
-    SQL (0.1ms)  INSERT INTO "users" ("name", "email") VALUES (?, ?)  [["name", "Frank Sinatra"], ["email", "live@tilidie.io"]]
-    => #<User id: 4, name: "Frank Sinatra", email: "live@tilidie.io", token: nil>
-
-##### `update_by_api`
-
-Updates a record in your database. If no record matching the primary key is found, nothing happens.
-
-    # Spigot yaml file for the github service
-    user:
-      full_name: name
-      login: email
-      token: auth
-      spigot:
-        primary_key: email
-
-    # API Data
-    data = {"full_name":"Dino Baby","login":"dean@amore.io","token":"bcd456"}
-
-    #=> User.update_by_api(:github, data)
-    User Load (0.2ms)  SELECT "users".* FROM "users" WHERE "users"."email" = 'livetilidie' ORDER BY "active_users"."id" ASC LIMIT 1
-    SQL (0.1ms)  UPDATE "users" SET "name" = ?, token = ? WHERE "users"."id" = 3  [["name", "Dino Baby"], ["token", "bcd456"]]
-    => #<User id: 3, name: "Dino Baby", email: "dean@amore.io", token: "bcd456">
-
-##### `find_or_create_by_api`
-
-Query the database to find an existing record. If none is found, create one with the provided API data.
-
-##### `create_or_update_by_api`
-
-Query the database to find an existing record. If a record is found, update
-the record with the received API data. If no record is found, create one with
-the provided API data.
+## Installation
 
-## Configuration
+Add this line to your application's Gemfile:
 
-There are a handful of options that let you make spigot work the way you need.
+    gem 'spigot'
 
-    logger:
-      Specify a logger you would like Spigot to log to.
-      type:    Object
-      default: Logger.new(STDOUT)
+And then execute:
 
-    options_key:
-      The key which Spigot uses for configuring a resource map.
-      type:    String
-      default: 'spigot'
+    $ bundle
 
-    path:
-      The directory which holds all the yaml files for the implemented services
-      type:    String
-      default: 'config/spigot'
+Or install it yourself as:
 
-    translations:
-      A map that, if present, overrides the resource maps found in the `path` directory
-      type:    Hash
-      default: nil
+    $ gem install spigot
 
 ## Contributing
 

data/lib/spigot/patch.rb

@@ -0,0 +1,11 @@
+class String
+  # Don't really like patching string here,
+  # but it's too clean not to.
+  def underscore
+    self.gsub(/::/, '/').
+    gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
+    gsub(/([a-z\d])([A-Z])/,'\1_\2').
+    tr("-", "_").
+    downcase
+  end
+end

data/lib/spigot/translator.rb

@@ -1,4 +1,5 @@
 require 'yaml'
+require 'hashie'
 
 module Spigot
   class Translator
@@ -37,16 +38,17 @@ module Spigot
     ## #format(custom_map)
     # Formats the hash of data passed in to the format specified in the yaml file.
     #
-    # @param custom_map [Hash] Optional hash that you can prefer to use over the correlated translation.
-    def format(custom_map=nil)
-      translations = custom_map || mapping
-      formatted = {}
-      data.each_pair do |key, val|
-        next if key == Spigot.config.options_key
-        attribute = translations[key.to_s]
-        formatted.merge!(attribute.to_s => data[key]) unless attribute.nil?
+    # @param custom_map  [Hash] Optional hash that you can prefer to use over the correlated translation.
+    # @param custom_data [Hash] Optional data that you can prefer to use over the @data currently on the object.
+    def format(custom_map=nil, custom_data=nil)
+      map     = Hashie::Mash.new(custom_map || mapping)
+      dataset = custom_data || data
+
+      if dataset.is_a?(Array)
+        dataset.map{|n| translate(map, n) }
+      elsif dataset.is_a?(Hash)
+        translate(map, dataset)
       end
-      formatted
     end
 
     ## #id
@@ -97,23 +99,52 @@ module Spigot
     # Return a hash of the data map currently being used by this translator, including options.
     def mapping
       return @mapping if defined?(@mapping)
-      @mapping = translations[resource_key.to_s]
+      @mapping = translations[resource_key]
       raise MissingResourceError, "There is no #{resource_key} mapping for #{service}" if @mapping.nil?
       @mapping
     end
 
     private
 
+    def translate(map, dataset)
+      formatted = {}
+
+      if dataset.is_a?(Array)
+        return dataset.map{|element| translate(map, element)}
+      else
+        dataset.each_pair do |key, val|
+          next if key == Spigot.config.options_key
+          attribute = map[key]
+          next if attribute.nil?
+
+          result = attribute.is_a?(Hash) ? translate(attribute, val) : val
+          formatted.merge! mergeable_content(key, result, map)
+        end
+      end
+
+      formatted
+    end
+
+    def mergeable_content(key, value, map)
+      if value.is_a?(Array)
+        {key.to_s => value}
+      elsif value.is_a?(Hash)
+        value
+      else
+        {map[key] => value}
+      end
+    end
+
     def condition_keys
       options['conditions'].to_s.split(',').map(&:strip)
     end
 
     def resource_key
-      resource.to_s.downcase.gsub('::', '/')
+      resource.to_s.underscore
     end
 
     def translations
-      @translations ||= Spigot.config.translations || YAML.load(translation_file)
+      @translations ||= Hashie::Mash.new(Spigot.config.translations || YAML.load(translation_file))
     end
 
     def translation_file

data/lib/spigot/version.rb

@@ -1,3 +1,3 @@
 module Spigot
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/lib/spigot.rb

@@ -1,5 +1,6 @@
 require "spigot/version"
 require "spigot/errors"
+require "spigot/patch"
 
 module Spigot
   autoload :Configuration, 'spigot/configuration'

data/spec/fixtures/api_data.rb

@@ -13,6 +13,27 @@ module Spigot
       {'full_name' => 'Frank Sinatra', 'login' => 'livetilidie', 'auth_token' => '456bcd'}
     end
 
+    def self.nested_user
+      {'full_name' => 'Dean Martin', 'login' => {
+        'email' => 'dino@amore.io',
+        'user_name' => 'classyasfuck'
+      }, 'auth_token' => '123abc'}
+    end
+
+    def self.double_nested_user
+      {'full_name' => 'Dean Martin', 'login' => {
+        'contact' => {'work_email' => 'dino@amore.io', 'user_name' => 'classyasfuck' }
+      }, 'auth_token' => '123abc'}
+    end
+
+    def self.user_array
+      [{'full_name' => 'Dean Martin', 'login' => 'classyasfuck'}, {'full_name' => 'Frank Sinatra', 'login' => 'livetilidie'}]
+    end
+
+    def self.nested_user_array
+      {'account' => 'Rockafella', 'users' => user_array, 'count' => 2}
+    end
+
     def self.basic_post
       {'title' => 'Brief Article', 'body' => 'lorem ipsum'}
     end

data/spec/fixtures/mappings/active_user_map.rb

@@ -4,19 +4,19 @@ module Spigot
     class ActiveUser
 
       def self.basic
-        {'activeuser' => base}
+        {'active_user' => base}
       end
 
       def self.with_options
-        {'activeuser' => base.merge('spigot' => options)}
+        {'active_user' => base.merge('spigot' => options)}
       end
 
       def self.non_unique_key
-        {'activeuser' => base.merge('auth_token' => 'token', 'spigot' => non_unique)}
+        {'active_user' => base.merge('auth_token' => 'token', 'spigot' => non_unique)}
       end
 
       def self.with_invalid_options
-        {'activeuser' => base.merge('spigot' => invalid_options)}
+        {'active_user' => base.merge('spigot' => invalid_options)}
       end
 
       private

data/spec/fixtures/mappings/user_map.rb

@@ -6,6 +6,32 @@ module Spigot
         {'user' => base}
       end
 
+      def self.symbolized
+        {user: {full_name: 'name', login: 'username'}}
+      end
+
+      def self.nested
+        {'user' => base.merge('login' => {'email' => 'contact', 'user_name' => 'username'})}
+      end
+
+      def self.nested_twice
+        {'user' => base.merge('login' => {
+          'contact' => {'work_email' => 'email', 'user_name' => 'username'}
+        })}
+      end
+
+      def self.array
+        {'user' => base}
+      end
+
+      def self.nested_array
+        {'user' => {'account' => 'name', 'count' => 'user_count', 'users' => base}}
+      end
+
+      def self.nested_account_members
+        {'activeuser' => {'account_name' => 'name', 'url' => 'url', 'members' => {'login' => 'email', 'full_name' => 'name'}}}
+      end
+
       def self.with_options
         {'user' => base.merge('spigot' => options)}
       end

data/spec/spigot/translator_spec.rb

@@ -45,6 +45,18 @@ describe Spigot::Translator do
       end
     end
 
+    context 'with a symbol keyed map' do
+      let(:subject){Spigot::Translator.new(:github, User.new, Spigot::ApiData.basic_user)}
+
+      context 'with a basic mapping' do
+        with_mapping(:basic_user, Spigot::Mapping::User.symbolized)
+
+        it 'reads one layer' do
+          expect(subject.format).to eq({'name' => 'Dean Martin', 'username' => 'classyasfuck'})
+        end
+      end
+    end
+
     context 'and a valid resource map' do
       with_mapping(:basic_user, Spigot::Mapping::User.basic)
 
@@ -64,12 +76,46 @@ describe Spigot::Translator do
         end
       end
 
-      context 'with a mapping containing several resources' do
-        with_mapping(:multiple_resources, Spigot::Mapping.multiple_resources)
+      context 'with a mapping containing nested data' do
+        let(:subject){Spigot::Translator.new(:github, User.new, Spigot::ApiData.nested_user)}
+        with_mapping(:basic_user, Spigot::Mapping::User.nested)
 
-        it 'selects the user map' do
-          expect(subject.format).to eq({'name' => 'Dean Martin', 'username' => 'classyasfuck'})
+        it 'traverses into the nested hash' do
+          expect(subject.format).to eq({
+            'name' => 'Dean Martin',
+            'username' => 'classyasfuck',
+            'contact' => 'dino@amore.io'
+          })
         end
+
+        context 'twice' do
+          with_mapping(:basic_user, Spigot::Mapping::User.nested_twice)
+          let(:subject){Spigot::Translator.new(:github, User.new, Spigot::ApiData.double_nested_user)}
+
+          it 'traverses multiple levels' do
+            expect(subject.format.values).to include(*['Dean Martin','classyasfuck','dino@amore.io'])
+          end
+        end
+      end
+    end
+
+    context 'with an array of values' do
+      let(:subject){Spigot::Translator.new(:github, User.new, Spigot::ApiData.user_array)}
+      with_mapping(:basic_user, Spigot::Mapping::User.basic)
+
+      it 'returns an array of formatted data' do
+        expect(subject.format.length).to eq(2)
+        expect(subject.format.map{|u| u['name']}).to include('Dean Martin', 'Frank Sinatra')
+      end
+    end
+
+    context 'with a nested array of values' do
+      let(:subject){Spigot::Translator.new(:github, User.new, Spigot::ApiData.nested_user_array)}
+      with_mapping(:basic_user, Spigot::Mapping::User.nested_array)
+
+      it 'handles a nested array of values' do
+        expect(subject.format.keys).to include('name', 'users', 'user_count')
+        expect(subject.format['users']).to be_a(Array)
       end
     end
 

data/spigot.gemspec

@@ -18,11 +18,11 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency 'activerecord'
+  spec.add_dependency 'hashie'
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec"
   spec.add_development_dependency "mocha"
-  spec.add_development_dependency 'hashie'
   spec.add_development_dependency 'sqlite3'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: spigot
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Matthew Werner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-11-15 00:00:00.000000000 Z
+date: 2013-11-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -25,35 +25,35 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: hashie
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - '>='
       - !ruby/object:Gem::Version
-        version: '1.3'
-  type: :development
+        version: '0'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - '>='
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '1.3'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
@@ -67,7 +67,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: mocha
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
@@ -81,7 +81,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: hashie
+  name: mocha
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
@@ -132,6 +132,7 @@ files:
 - lib/spigot/config/spigot/github.yml
 - lib/spigot/configuration.rb
 - lib/spigot/errors.rb
+- lib/spigot/patch.rb
 - lib/spigot/proxy.rb
 - lib/spigot/record.rb
 - lib/spigot/translator.rb