bomb_defuser 0.0.4

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+vendor

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in bomb_defuser.gemspec
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Lucas Húngaro
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.textile

@@ -0,0 +1,105 @@
+h1. bomb_defuser
+
+A simple wrapper for the awesome GiantBomb.com API.
+
+Does bomb_defuser helps your daily work with Ruby? So, "please recommend me in Work With Rails":http://workingwithrails.com/recommendation/new/person/9370-lucas-h-ngaro and thanks for your kindness! :)
+
+h2. How?
+
+First, install the gem:
+
+<pre>
+$ [sudo] gem install bomb_defuser
+</pre>
+
+Then, add it as a dependency of your code using your favorite way (a simple require or mechanisms like the Bundler gem).
+
+Using it is really simple.
+
+First, you need an API key. Then, configure bomb_defuser to use it:
+
+<pre>
+BombDefuser::Configuration.api_key = "my api key"
+</pre>
+
+Now to the real data consumption. There are two kinds of entities: a Resource (single entity) and a ResourceList (list of entities).
+
+An example of Resource is a Game. To get data about a particular game you can do the following:
+
+<pre>
+>> BombDefuser::Game.details(17280)
+=> <#Hashie::Mash name="BioShock" ...>
+</pre>
+
+An example of a ResourceList is a GameList. To get a list of games you can do the following:
+
+<pre>
+>> BombDefuser::GameList.fetch
+=> [<#Hashie::Mash name="BioShock" ...>, <#Hashie::Mash name="Civilization V" ...>, ...]
+</pre>
+
+As you can see, the gem makes use of "Hashie's":https://github.com/intridea/hashie Mash, which basically is a Hash with attribute accessors for all keys, meaning you can use the dot notation to access values:
+
+<pre>
+>> game = BombDefuser::Game.details(17280)
+=> <#Hashie::Mash name="BioShock" ...>
+>> game.name
+=> "BioShock"
+</pre>
+
+For a Resource, the return will always be a Mash instance. For a ResourceList, it will be an Array of Mash instances.
+
+A Resource has one method (details) which receives the entity id.
+
+A ResourceList has one method (fetch) which receives two numeric parameters regarding pagination: the first one is the current page and the second one is the amount of elements per page.
+
+The GameList can also send a "platforms" parameter, which is an Array containing the ids of the gaming platforms that will be used to filter the results:
+
+<pre>
+>> BombDefuser::GameList.platforms = [35, 129]
+=> [35, 129]
+>> BombDefuser::GameList.fetch
+=> [<#Hashie::Mash name="Uncharted" ...>, <#Hashie::Mash name="God of War" ...>, ...]
+</pre>
+
+The other lists do not feature additional filters at the moment.
+
+For further reference, please check the "official API documentation":http://api.giantbomb.com/documentation/.
+
+h3. Available endpoints
+
+Resources:
+
+* Company
+* Game
+* Genre
+* Platform
+* Theme
+
+Resource lists:
+
+* Companies
+* Games
+* Genres
+* Platforms
+* Themes
+
+h3. Additional configuration
+
+Besides the API key, the Configuration class allows you to configure an adapter to make HTTP requests (you can use the included "CurbAdapter":https://github.com/lucashungaro/bomb_defuser/blob/master/lib/curb_adapter.rb. and its specs as an example of implementation) and a logger (STDOUT by default).
+
+h2. Note on Patches/Pull Requests
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+
+h3. License
+
+sentinel is released under the MIT license. See "MIT LICENSE":https://github.com/lucashungaro/bomb_defuser/blob/master/MIT-LICENSE.
+

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bomb_defuser.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "bomb_defuser/version"
+
+Gem::Specification.new do |s|
+  s.name        = "bomb_defuser"
+  s.version     = BombDefuser::VERSION
+  s.authors     = ["Lucas Húngaro"]
+  s.email       = ["lucashungaro@gmail.com"]
+  s.homepage    = "https://github.com/lucashungaro/bomb_defuser"
+  s.summary     = %q{A simple wrapper for the awesome GiantBomb.com API}
+  s.description = %q{A simple wrapper for the awesome GiantBomb.com API}
+
+  s.rubyforge_project = "bomb_defuser"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "rspec", "2.6"
+  s.add_development_dependency "webmock", "1.7.6"
+
+  s.add_runtime_dependency "curb", "0.7.15"
+  s.add_runtime_dependency "hashie", "1.1.0"
+  s.add_runtime_dependency "yajl-ruby", "0.8.3"
+end

data/lib/bomb_defuser.rb

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+require "bomb_defuser/version"
+
+require "bomb_defuser/curb_adapter"
+require "bomb_defuser/errors"
+require "bomb_defuser/request"
+require "bomb_defuser/response_handler"
+require "bomb_defuser/resource"
+require "bomb_defuser/resource_list"
+
+require "bomb_defuser/company"
+require "bomb_defuser/company_list"
+require "bomb_defuser/configuration"
+require "bomb_defuser/game"
+require "bomb_defuser/game_list"
+require "bomb_defuser/genre"
+require "bomb_defuser/genre_list"
+require "bomb_defuser/platform"
+require "bomb_defuser/platform_list"
+require "bomb_defuser/theme"
+require "bomb_defuser/theme_list"
+
+require "curb"
+require "hashie"
+require "logger"
+require "yajl"

data/lib/bomb_defuser/company.rb

@@ -0,0 +1,8 @@
+# -*- encoding: utf-8 -*-
+module BombDefuser
+  class Company
+    extend Resource
+
+    @resource = "company"
+  end
+end

data/lib/bomb_defuser/company_list.rb

@@ -0,0 +1,8 @@
+# -*- encoding: utf-8 -*-
+module BombDefuser
+  class CompanyList
+    extend ResourceList
+
+    @resource = "companies"
+  end
+end

data/lib/bomb_defuser/configuration.rb

@@ -0,0 +1,15 @@
+# -*- encoding: utf-8 -*-
+require "logger"
+
+module BombDefuser
+  class Configuration
+    BASE_URL = "http://api.giantbomb.com"
+
+    @http_library_adapter = CurbAdapter
+    @logger = Logger.new(STDOUT)
+
+    class << self
+      attr_accessor :api_key, :http_library_adapter, :logger
+    end
+  end
+end

data/lib/bomb_defuser/curb_adapter.rb

@@ -0,0 +1,18 @@
+# -*- encoding : utf-8 -*-
+require "ostruct"
+
+module BombDefuser
+  class CurbAdapter
+    def self.http_get(url, headers = {})
+      begin
+        response = Curl::Easy.http_get(url) {|config| config.headers = headers }
+
+        if response
+          OpenStruct.new(:body => response.body_str, :code => response.response_code, :headers => response.headers)
+        end
+      rescue StandardError => e
+        raise Errors::WebServiceNotAvailableError, e.message
+      end
+    end
+  end
+end

data/lib/bomb_defuser/errors.rb

@@ -0,0 +1,9 @@
+# -*- encoding: utf-8 -*-
+module BombDefuser
+  module Errors
+    class InvalidRequestError < StandardError; end
+    class RequestFailedError < StandardError; end
+    class UnrecognizedResponseError < StandardError; end
+    class WebServiceNotAvailableError < StandardError; end
+  end
+end

data/lib/bomb_defuser/game.rb

@@ -0,0 +1,8 @@
+# -*- encoding: utf-8 -*-
+module BombDefuser
+  class Game
+    extend Resource
+
+    @resource = "game"
+  end
+end

data/lib/bomb_defuser/game_list.rb

@@ -0,0 +1,17 @@
+# -*- encoding: utf-8 -*-
+module BombDefuser
+  class GameList
+    extend ResourceList
+
+    @resource = "games"
+
+    class << self
+      attr_accessor :platforms
+    end
+
+    def self.include_additional_parameters
+      self.platforms ||= []
+      params[:platforms] = platforms.join(",") unless platforms.empty?
+    end
+  end
+end

data/lib/bomb_defuser/genre.rb

@@ -0,0 +1,8 @@
+# -*- encoding: utf-8 -*-
+module BombDefuser
+  class Genre
+    extend Resource
+
+    @resource = "genre"
+  end
+end

data/lib/bomb_defuser/genre_list.rb

@@ -0,0 +1,8 @@
+# -*- encoding: utf-8 -*-
+module BombDefuser
+  class GenreList
+    extend ResourceList
+
+    @resource = "genres"
+  end
+end

data/lib/bomb_defuser/platform.rb

@@ -0,0 +1,8 @@
+# -*- encoding: utf-8 -*-
+module BombDefuser
+  class Platform
+    extend Resource
+
+    @resource = "platform"
+  end
+end

data/lib/bomb_defuser/platform_list.rb

@@ -0,0 +1,8 @@
+# -*- encoding: utf-8 -*-
+module BombDefuser
+  class PlatformList
+    extend ResourceList
+
+    @resource = "platforms"
+  end
+end

data/lib/bomb_defuser/request.rb

@@ -0,0 +1,43 @@
+# -*- encoding: utf-8 -*-
+module BombDefuser
+  class Request
+    def initialize(resource, params = {})
+      self.request_url = "#{Configuration::BASE_URL}/#{resource}/"
+      self.request_params = build_params(params)
+      self.logger = Configuration.logger
+      self.http_client = Configuration.http_library_adapter
+    end
+
+    def get(response_handler = ResponseHandler.new)
+      url = build_url
+      logger.info("GET on #{url}")
+
+      response = http_client.http_get(url)
+      response_handler.process(response)
+    end
+
+    private
+    attr_accessor :http_client, :logger, :request_url, :request_params
+
+    def build_params(params)
+      building_params = {:format => "json", :api_key => Configuration.api_key}
+
+      if limit = params.delete(:per_page)
+        building_params[:limit] = limit
+        building_params[:offset] = (params.delete(:page_number) - 1) * limit
+      end
+
+      building_params.merge!(params)
+      building_params
+    end
+
+    def build_url
+      params = request_params.inject([]) do |memo, param_pair|
+        memo << "#{param_pair[0]}=#{param_pair[1]}"
+      end
+
+      building_url = request_url.dup
+      building_url << "?#{params.join('&')}"
+    end
+  end
+end

data/lib/bomb_defuser/resource.rb

@@ -0,0 +1,12 @@
+# -*- encoding: utf-8 -*-
+module BombDefuser
+  module Resource
+    def details(resource_id)
+      request = Request.new("#{resource}/#{resource_id}")
+      request.get
+    end
+
+    private
+    attr_accessor :resource
+  end
+end

data/lib/bomb_defuser/resource_list.rb

@@ -0,0 +1,15 @@
+# -*- encoding: utf-8 -*-
+module BombDefuser
+  module ResourceList
+    def fetch(page_number = 1, per_page = 100)
+      self.params = {:page_number => page_number, :per_page => per_page}
+      include_additional_parameters
+
+      request = Request.new(resource, params)
+      request.get
+    end
+
+    private
+    attr_accessor :params, :resource
+  end
+end

data/lib/bomb_defuser/response_handler.rb

@@ -0,0 +1,57 @@
+# -*- encoding: utf-8 -*-
+module BombDefuser
+  class ResponseHandler
+    def initialize(parser = Yajl::Parser.new)
+      self.parser = parser
+      self.logger = Configuration.logger
+    end
+
+    def process(response)
+      raise(Errors::UnrecognizedResponseError, "The response can't be nil") if response.nil?
+
+      parse(response, parser)
+      result_size > 1 ? process_collection : process_single_resource
+    end
+
+    private
+    attr_accessor :logger, :parser, :result_size, :results
+
+    def parse(response, parser)
+      if valid_response?(response)
+        parsed_response = parser.parse(response.body)
+        handle_api_details(parsed_response)
+      else
+        raise Errors::UnrecognizedResponseError, "Your request didn't return a standard response from BombDefuser's API. Please check the log."
+      end
+    end
+
+    def valid_response?(response)
+      if response.code == 200
+        true
+      else
+        logger.info("Request failed. Http status: #{response.code}. Body: #{response.body}")
+        raise Errors::RequestFailedError, "The request failed with http code #{response.code}"
+      end
+    end
+
+    def handle_api_details(parsed_response)
+      if parsed_response["status_code"] == 1
+        self.result_size = parsed_response["number_of_page_results"]
+        self.results = parsed_response["results"]
+      else
+        logger.info("The API returned an error: #{parsed_response["error"]}")
+        raise Errors::InvalidRequestError, parsed_response["error"]
+      end
+    end
+
+    def process_collection
+      results.inject([]) do |collection, element|
+        collection << Hashie::Mash.new(element)
+      end
+    end
+
+    def process_single_resource
+      Hashie::Mash.new(results)
+    end
+  end
+end