spigot 0.0.1

data/lib/spigot/base.rb

@@ -0,0 +1,43 @@
+require 'active_record'
+module Spigot
+  module Base
+    def self.included(base)
+      base.send(:extend, self::ClassMethods)
+      base.send(:extend, Spigot::ActiveRecord::ClassMethods) if active_record?(base)
+    end
+
+    module ClassMethods
+      # #self.new_by_api(service, api_data)
+      # Instantiate a new object mapping the api data to the calling object's attributes
+      #
+      # @param service [Symbol] Service which will be doing the translating. Must have a corresponding yaml file
+      # @param api_data [Hash] The data as received from the remote api, unformatted.
+      def new_by_api(service, api_data)
+        Record.instantiate(self, formatted_api_data(service, api_data))
+      end
+
+      # #self.formatted_api_data(service, api_data)
+      # Create a Spigot::Translator for the given service and return the formatted data.
+      #
+      # @param service [Symbol] Service which will be doing the translating. Must have a corresponding yaml file
+      # @param api_data [Hash] The data as received from the remote api, unformatted.
+      def formatted_api_data(service, api_data)
+        Translator.new(service, self, api_data).format
+      end
+
+      # #self.spigot
+      # Return a Spigot::Proxy that provides accessor methods to the spigot library
+      #
+      # @param service [Symbol] Service which pertains to the data being processed on the implementation
+      def spigot(service)
+        Spigot::Proxy.new(service, self)
+      end
+    end
+
+    private
+
+    def self.active_record?(klass)
+      defined?(ActiveRecord) && klass < ::ActiveRecord::Base
+    end
+  end
+end

data/lib/spigot/config/spigot/github.yml

@@ -0,0 +1,7 @@
+user:
+  name:
+    attribute: 'name'
+    options:
+      id: true
+
+  username: 'login'

data/lib/spigot/configuration.rb

@@ -0,0 +1,28 @@
+require 'singleton'
+
+module Spigot
+  class Configuration
+    include Singleton
+
+    attr_accessor :path, :translations, :options_key, :logger
+
+    @@defaults = {
+      path: 'config/spigot',
+      translations: nil,
+      options_key: 'spigot',
+      logger: nil
+    }
+
+    def self.defaults
+      @@defaults
+    end
+
+    def initialize
+      reset
+    end
+
+    def reset
+      @@defaults.each_pair{|k,v| self.send("#{k}=",v)}
+    end
+  end
+end

data/lib/spigot/errors.rb

@@ -0,0 +1,8 @@
+module Spigot
+  class MissingServiceError  < StandardError; end
+  class InvalidServiceError  < StandardError; end
+  class MissingResourceError < StandardError; end
+  class InvalidResourceError < StandardError; end
+  class InvalidDataError     < StandardError; end
+  class InvalidSchemaError   < StandardError; end
+end

data/lib/spigot/proxy.rb

@@ -0,0 +1,40 @@
+module Spigot
+  class Proxy
+
+    ## Proxy
+    #
+    # Spigot::Proxy provides accessor methods used by the implementation
+    # that could be useful for development or custom behavior
+
+    attr_reader :resource, :service
+
+    ## #initialize(resource)
+    # Method to initialize a proxy.
+    #
+    # @param service [String] This is the service that dictates the proxy.
+    # @param resource [Object] This is the class implementing the proxy.
+    def initialize(service, resource)
+      @service  = service
+      @resource = resource
+    end
+
+    ## #translator
+    # Instantiate a Spigot::Translator object with the contextual service and resource
+    def translator
+      Translator.new(service, resource)
+    end
+
+    ## #map
+    # Return a hash of the data map the current translator is using
+    def map
+      translator.mapping.reject{|k,v| k == 'spigot'}
+    end
+
+    ## #options
+    # Return a hash of any service specific options for this translator. `Spigot.config` not included
+    def options
+      translator.mapping['spigot'] || {}
+    end
+
+  end
+end

data/lib/spigot/record.rb

@@ -0,0 +1,71 @@
+module Spigot
+  class Record
+
+    ## Record
+    #
+    # Spigot::Record is responsible for the instantiation and creation
+    # of objects with the formatted data received from Spigot::Translator.
+
+    attr_reader :resource, :record, :data
+
+    # #initialize(resource, data)
+    # Method to initialize a record.
+    #
+    # @param resource [Object] This is the class implementing the record.
+    # @param data     [Hash]   The already formatted data used to produce the object.
+    # @param record   [Object] Optional record of `resource` type already in database.
+    def initialize(resource, data, record=nil)
+      @resource = resource
+      @data     = data
+      @record   = record
+    end
+
+    ## #instantiate(resource, data)
+    # Executes the initialize method on the implementing resource with formatted data.
+    #
+    # @param resource [Object] This is the class implementing the record.
+    # @param data     [Hash]   The already formatted data used to produce the object.
+    def self.instantiate(resource, data)
+      new(resource, data).instantiate
+    end
+
+    ## #create(resource, data)
+    # Executes the create method on the implementing resource with formatted data.
+    #
+    # @param resource [Object] This is the class implementing the record.
+    # @param data     [Hash]   The already formatted data used to produce the object.
+    def self.create(resource, data)
+      new(resource, data).create
+    end
+
+    ## #update(resource, data)
+    # Assigns the formatted data to the resource and saves.
+    #
+    # @param resource [Object] This is the class implementing the record.
+    # @param record   [Object] Optional record of `resource` type already in database.
+    # @param data     [Hash]   The already formatted data used to produce the object.
+    def self.update(resource, record, data)
+      new(resource, data, record).update
+    end
+
+    ## #instantiate
+    # Executes the initialize method on the implementing resource with formatted data.
+    def instantiate
+      resource.new(data)
+    end
+
+    ## #create
+    # Executes the create method on the implementing resource with formatted data.
+    def create
+      resource.create(data)
+    end
+
+    ## #update
+    # Assigns the formatted data to the resource and saves.
+    def update
+      record.assign_attributes(data)
+      record.save! if record.changed?
+    end
+
+  end
+end

data/lib/spigot/translator.rb

@@ -0,0 +1,128 @@
+require 'yaml'
+
+module Spigot
+  class Translator
+
+    ## Translator
+    #
+    # Translator reads the yaml file in the spigot config directory for
+    # a given service. It looks up the key for the resource class name
+    # passed in, then translates the data received into the format described
+    # in the yaml file for that resource.
+    #
+    # Relevant Configuration:
+    # config.options_key  => The key which the Translator uses to configure a resource mapping.
+    # config.path         => The path which the Translator will look in to find the mappings.
+    # config.translations => A hash that overrides any mappings found in the `path` directory.
+
+    attr_reader :service, :resource
+    attr_accessor :data
+
+    OPTIONS = %w(primary_key foreign_key conditions).freeze
+
+    ## #initialize(service, resource, data)
+    # Method to initialize a translator.
+    #
+    # @param service  [Symbol] Service doing the translating. Must have a corresponding yaml file.
+    # @param resource [Object] This is the class using the translator.
+    # @param data     [Hash] Data in the format received by the api (optional).
+    def initialize(service, resource, data={})
+      @service = service
+      raise InvalidServiceError, 'You must provide a service name' if service.nil? || service == ''
+      @resource = resource.is_a?(Class) ? resource : resource.class
+      raise InvalidResourceError, 'You must provide a calling resource' if resource.nil?
+      @data = data || {}
+    end
+
+    ## #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?
+      end
+      formatted
+    end
+
+    ## #id
+    # The value at the foreign_key attribute specified in the resource options, defaults to 'id'.
+    def id
+      @id ||= lookup(foreign_key)
+    end
+
+    ## #lookup(attribute)
+    # Find the value in the unformatted api data that matches the passed in key.
+    #
+    # @param attribute [String] The key pointing to the value you wish to lookup.
+    def lookup(attribute)
+      data.detect{|k, v| k.to_s == attribute.to_s }.try(:last)
+    end
+
+    ## #options
+    # Available options per resource.
+    #
+    # @primary_key:
+    #   Default: "#{service}_id"
+    #   Name of the column in your local database that serves as id for an external resource.
+    # @foreign_key:
+    #   Default: "id"
+    #   Name of the key representing the resource's ID in the data received from the API.
+    # @conditions:
+    #   Default: nil
+    #   Array of attributes included in the database query, these are names of columns in your database.
+    def options
+      @options ||= mapping[Spigot.config.options_key] || {}
+    end
+
+    def primary_key
+      options['primary_key'] || "#{service}_id"
+    end
+
+    def foreign_key
+      options['foreign_key'] || mapping.invert[primary_key] || 'id'
+    end
+
+    def conditions
+      p_keys = [*(condition_keys.blank? ? primary_key : condition_keys)].map(&:to_s)
+      keys   = mapping.select{|k, v| p_keys.include?(v.to_s) }
+      format(keys)
+    end
+
+    ## #mapping
+    # 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]
+      raise MissingResourceError, "There is no #{resource_key} mapping for #{service}" if @mapping.nil?
+      @mapping
+    end
+
+    private
+
+    def condition_keys
+      options['conditions'].to_s.split(',').map(&:strip)
+    end
+
+    def resource_key
+      resource.to_s.downcase.gsub('::', '/')
+    end
+
+    def translations
+      @translations ||= Spigot.config.translations || YAML.load(translation_file)
+    end
+
+    def translation_file
+      begin
+        @translation_file ||= File.read(File.join(Spigot.config.path, "#{service.to_s}.yml"))
+      rescue Errno::ENOENT => e
+        raise MissingServiceError, "There is no service map for #{service} defined"
+      end
+    end
+
+  end
+end

data/lib/spigot/version.rb

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

data/script/console.rb

@@ -0,0 +1,31 @@
+require 'active_record'
+require 'spigot'
+
+ActiveRecord::Base.logger = Spigot.logger
+require File.join(Spigot.root, 'spec', 'support', 'active_record')
+
+class ActiveUser < ActiveRecord::Base
+  include Spigot::Base
+end
+
+map = {'activeuser' => {
+  'name' => 'name',
+  'username' => 'login',
+  'spigot' => {
+    'primary_key' => 'username'
+  }
+}}
+
+conditions = {'activeuser' => {
+  'name' => 'name',
+  'login' => 'username',
+  'spigot' => {
+    'primary_key' => 'username'
+  }
+}}
+
+Spigot.configure do |config|
+  config.translations = conditions
+end
+
+user = ActiveUser.create(name: 'Matt', username: 'mttwrnr', token: 'abc123')

data/spec/fixtures/api_data.rb

@@ -0,0 +1,25 @@
+module Spigot
+  class ApiData
+
+    def self.basic_user
+      {'full_name' => 'Dean Martin', 'login' => 'classyasfuck'}
+    end
+
+    def self.user
+      {'full_name' => 'Dean Martin', 'login' => 'classyasfuck', 'auth_token' => '123abc'}
+    end
+
+    def self.updated_user
+      {'full_name' => 'Frank Sinatra', 'login' => 'livetilidie', 'auth_token' => '456bcd'}
+    end
+
+    def self.basic_post
+      {'title' => 'Brief Article', 'body' => 'lorem ipsum'}
+    end
+
+    def self.post
+      {'title' => 'Regular Article', 'body' => 'dolor sit amet', 'author' => 'Dean Martin'}
+    end
+
+  end
+end

data/spec/fixtures/mappings/active_user_map.rb

@@ -0,0 +1,42 @@
+module Spigot
+  module Mapping
+
+    class ActiveUser
+
+      def self.basic
+        {'activeuser' => base}
+      end
+
+      def self.with_options
+        {'activeuser' => base.merge('spigot' => options)}
+      end
+
+      def self.non_unique_key
+        {'activeuser' => base.merge('auth_token' => 'token', 'spigot' => non_unique)}
+      end
+
+      def self.with_invalid_options
+        {'activeuser' => base.merge('spigot' => invalid_options)}
+      end
+
+      private
+
+      def self.base
+        {'full_name' => 'name', 'login' => 'username'}
+      end
+
+      def self.options
+        {'primary_key' => 'username', 'foreign_key' => 'login'}
+      end
+
+      def self.non_unique
+        {'primary_key' => 'token', 'foreign_key' => 'auth_token'}
+      end
+
+      def self.invalid_options
+        {'primary_key' => 'nosuchcolumn', 'foreign_key' => 'nosuchkey'}
+      end
+    end
+
+  end
+end